npm ERESOLVE 对等依赖冲突 — 不靠 --force 解决

用 npm ls、npm explain 与 peerDependencies 元数据定位冲突边，升级版本或使用精确 overrides，避免用 --legacy-peer-deps 掩盖问题。

现象

安装时报 npm ERR! code ERESOLVE 与 unable to resolve dependency tree；错误中出现 peer react@"^19.0.0" 之类的范围；加上 --legacy-peer-deps 能装但 CI 仍失败；升级某个 UI 库后突然出现。

诊断

先完整读取错误中的依赖关系：

npm install 2>&1 | sed -n '/ERESOLVE/,/npm ERR!/p' | head -40
npm ls react react-dom
npm explain react
npm view some-ui-kit@latest version peerDependencies --json

Found 与 Could not resolve 两行给出已安装版本和要求的对等范围，While resolving 指出是哪条依赖链引入的。npm ls 中的 INVALID 或 UNMET PEER 标记就是冲突边；npm explain 能区分 React 是直接依赖、插件的 peer，还是传递依赖，从而决定升级谁。再查看插件最新版声明的 peer 范围，确认它是否已支持当前框架版本。

修复

优先让两边的 major 版本范围重叠，例如同时升级 react 与 react-dom，或换用仍在维护的插件。传递依赖滞后时，使用精确的 overrides：

{
  "overrides": {
    "some-ui-kit": {
      "react": "$react"
    }
  }
}

--legacy-peer-deps 只能作为紧急上线时的临时手段，并应记录原因；--force 会安装 npm 已判定不兼容的树，不要使用。删除 lockfile 还可能顺带升级无关依赖。

验证

确认 npm ls 不再出现 INVALID 或 UNMET PEER，测试与生产构建均通过；在干净目录执行 npm ci，证明 lockfile 固化了同样的依赖树。如果只有加参数才能构建，说明不兼容仍然存在，迟早会在运行时暴露。