npm ERESOLVE — Peer 依赖冲突

症状

出现 npm ERR! code ERESOLVE 和 Could not resolve dependency；添加或升级包后安装失败，而旧 lockfile 可以安装；错误提到某个 peer 依赖范围与树中已有版本冲突。

诊断

npm install 2>&1 | head -60
npm ls <peer-package> --all
npm explain <package-name>

完整错误会列出正在安装的包、冲突的 peer 以及两个范围；比较语义化版本，而不只是包名。npm ls 显示是否存在重复版本（例如多个 React 版本）；npm explain 显示依赖路径，帮助找到仍固定旧范围的包。

根因

npm 构建一棵必须满足所有 peer 范围的依赖树。当两个包要求同一 peer 的不兼容范围，或 lockfile 中的版本超出要求时，npm 拒绝生成树并以 ERESOLVE 退出。

修复

1. 升级声明旧 peer 范围的包。
2. 把重复的共享依赖对齐到兼容的主版本。
3. 用干净安装重建 lockfile。
4. 只有在理解并测试组合后，才添加 overrides：

{
  "overrides": {
    "some-package": {
      "react": "$react"
    }
  }
}

$react 表示使用根项目解析到的版本，使 override 保持对齐。记录 override 的原因，并在上游修复后移除。

验证

• 在干净检出中 npm ci 成功。
• npm ls 没有 invalid peer 警告。
• 应用构建与测试通过。
• lockfile 已提交。
• CI 不需要 --legacy-peer-deps 或 --force。

--legacy-peer-deps 可以临时解除本地实验的阻塞，但会改变解析语义并隐藏真实不兼容；必须记录原因、影响包与移除日期，不能作为仓库默认。