01 · 依赖安装阶段

1.1 npm ERR! ERESOLVE unable to resolve dependency tree

现象:npm install 时报 peerDependency 冲突。

原因:react 18 / antd 5 等包对 peer 版本有要求,新增包对 react 版本要求不一致。

定位:

• 看 npm err! While resolving: 这一行 — 是哪个包触发了冲突
• 看 npm err! Found: 与 npm err! Could not resolve dependency: — 期望版本 vs 实际版本

解决:

• 优先升级到兼容版本(在 npm 包页面查 peerDependencies)
• 临时绕过:npm i --legacy-peer-deps(不推荐长期使用)
• 锁版本:在 package.json 加:

  "overrides": {
    "react": "^18.3.1",
    "react-dom": "^18.3.1"
  }
  

1.2 EPERM: operation not permitted / EBUSY(Windows)

现象:Windows 下安装 / 删除 node_modules 报锁定。

原因:VSCode、dev server、文件资源管理器、杀毒软件占用文件句柄。

解决:

1. 关闭 dev server(Ctrl+C)
2. 关闭 VSCode 或在 settings 关闭 files.watcherExclude 中的 node_modules 索引
3. 用管理员 PowerShell:

   Remove-Item -Recurse -Force node_modules
   

4. 仍不行重启系统(文件句柄释放)

1.3 Cannot find module 'xxx' 安装后仍报错

定位:

1. npm ls xxx 看是否真装上、装了几份
2. 看是否拼错包名:
   • react-router ❌ vs react-router-dom ✅
   • @types/node ❌ 装到 dependencies vs ✅ devDependencies
3. monorepo 下确认在正确 workspace 装(npm i xxx -w frontend)

1.4 npm WARN deprecated xxx 大量警告

说明:仅警告,不影响运行。但要留意 transitive 依赖里的安全漏洞包。

处理:

• npm audit 看安全报告
• npm audit fix 自动升级(不会破坏 semver)
• npm audit fix --force 谨慎,可能升大版本

1.5 lock 文件冲突

现象:git pull 后 package-lock.json 冲突。

解决:

• 不要手改 lock 文件
• 删除 lock,重新 npm install 生成
• 在 PR 里只让一个人改依赖,避免并行冲突

1.6 CI 上失败但本地正常

根因:本地有缓存的旧版本依赖,CI 是干净环境。

解决:

• CI 必须用 npm ci(严格按 lock 文件,失败比安装更快)
• 本地试试 rm -rf node_modules && npm ci 复现 CI 状态