npm突发Z_DATA_ERROR报错求助：本地Mac ARM执行npm install失败

问题背景 #

本地Mac ARM1设备与Linux生产环境服务器原本Node.js（生产环境为14.21.3）、npm（生产环境为6.14.18）版本一致，近期未修改代码，但执行npm install时出现以下错误：

code Z_DATA_ERROR
npm ERR! errno -3
npm ERR! zlib: incorrect data check

已尝试卸载重装npm、清理npm缓存/删除node_modules及package-lock.json、降级npm至6.14.15、通过nvm降级Node.js至14.17.6，问题仍未解决，推测生产环境执行npm install也会出现相同问题。

针对性解决方案 #

1. 切换npm源并重新校验缓存 #

zlib错误常因源服务器的包压缩包损坏或传输校验失败导致，切换至官方源或国内稳定源后重试：

• 切换至npm官方源：

  npm config set registry https://registry.npmjs.org/
  

• 或切换至国内镜像源：

  npm config set registry https://registry.npmmirror.com/
  

• 强制清理缓存后重新执行安装：

  npm cache clean --force
  rm -rf node_modules package-lock.json
  npm install
  

2. 对齐生产环境的Node.js/npm版本 #

之前的降级操作可能引入架构兼容问题，切回与生产环境完全一致的版本：

nvm install 14.21.3
nvm use 14.21.3
# 确认版本匹配
node -v # 应输出v14.21.3
npm -v # 应输出6.14.18
rm -rf node_modules package-lock.json
npm install

3. 针对Mac ARM架构的Rosetta兼容处理 #

部分依赖包仅提供x86预编译二进制包，ARM架构下解压时会触发校验错误，通过Rosetta兼容模式运行终端：

• 右键终端应用 → 「显示简介」
• 勾选「使用Rosetta打开」
• 重启终端后重新执行npm install

4. 排查可疑依赖包 #

若上述方法无效，观察npm install输出中最先触发错误的依赖包，尝试：

• 在package.json中放宽该依赖的版本范围（如将^1.2.3改为~1.2.3或指定稳定版本）
• 临时移除该依赖，确认是否能正常安装，再逐步排查替换

5. 生产环境预验证 #

在操作生产环境前，先在与生产环境系统、版本完全一致的测试服务器上执行npm install，确认问题复现及解决方案有效性，避免影响生产业务。

内容的提问来源于stack exchange，提问作者JAyenGreen