npm 常见报错速查

ERESOLVE unable to resolve dependency tree

出现场景：npm install 时依赖版本冲突

原因：两个包要求同一依赖的不兼容版本（npm 7+ 更严格）

解决方案：

1. 快速解决：npm install --legacy-peer-deps
2. 强制安装：npm install --force
3. 手动解决：查看冲突详情，安装兼容版本
4. 使用 overrides：在 package.json 中添加 "overrides" 字段指定版本

预防：定期更新依赖，避免版本差距过大

EACCES: permission denied

出现场景：npm install -g 全局安装时

原因：npm 全局目录需要 root 权限

解决方案：

1. 推荐：使用 nvm 管理 Node（自动解决权限问题）
2. 修改 npm prefix：mkdir ~/.npm-global && npm config set prefix ~/.npm-global
3. 将 ~/.npm-global/bin 添加到 PATH
4. 临时方案：sudo npm install -g（不推荐）

预防：使用 nvm 安装 Node.js，避免全局权限问题

npm ERR! network request to https://registry.npmjs.org failed

出现场景：npm install 下载包时

原因：网络连接问题、DNS 解析失败、或被防火墙阻止

解决方案：

1. 切换国内镜像：npm config set registry https://registry.npmmirror.com
2. 设置代理：npm config set proxy http://127.0.0.1:7890
3. 清除缓存重试：npm cache clean --force && npm install
4. 检查 DNS：nslookup registry.npmjs.org

预防：国内开发者默认使用 npmmirror 镜像

Error: Cannot find module 'xxx'

出现场景：运行 Node.js 应用时

原因：依赖未安装、node_modules 损坏、或路径错误

解决方案：

1. 重新安装依赖：rm -rf node_modules && npm install
2. 检查包是否在 package.json 中：npm ls <package>
3. 如果是全局命令：npm install -g <package>
4. 检查 require/import 路径是否正确

预防：确保 package.json 中声明了所有依赖，不依赖幽灵依赖

npm WARN EBADENGINE Unsupported engine

出现场景：npm install 时 Node.js 版本不满足要求

原因：包要求的 Node.js 版本与当前安装的不匹配

解决方案：

1. 查看要求的版本：npm info <package> engines
2. 升级 Node.js：nvm install <version> && nvm use <version>
3. 忽略警告（可能有风险）：npm install --ignore-engines
4. 使用 .nvmrc 文件锁定项目 Node 版本

预防：项目中添加 .nvmrc 文件，团队统一 Node.js 版本