npm ERR! ERESOLVE：peer dependency 冲突的四种解决策略

现象：npm install 直接拒绝执行

npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR!
npm ERR! Found: react@18.2.0
npm ERR! Could not resolve dependency:
npm ERR! peer react@"^17.0.0" from some-lib@2.1.0

npm 7+ 开始将 peer dependency 冲突从"警告"升级为"硬性阻断"——install 直接失败。这不是 npm 的 bug，是它在告诉你存在真实的兼容性风险。

什么是 peer dependency

一句话：库在说"我需要宿主应用里已经装了这个包，但我不会自己安装"。设计目的是让插件和框架共享同一份宿主框架代码，避免 bundle 里出现两个 React。

当两个包对 peer 版本的要求矛盾（一个要 React 17，一个要 React 18），npm 无法同时满足 → ERESOLVE 错误。

四种解决策略（按安全性排序）

策略一：修复实际版本冲突（最正确）

报错信息已经告诉你哪个包要什么版本。通常升级或降级一个直接依赖就能让所有 peer 范围重叠：

npm ls react               # 查看当前版本树
npm install some-lib@latest # 升级冲突包

策略二：--legacy-peer-deps（快速解锁）

npm install --legacy-peer-deps

让 npm 退回 6.x 行为：照样安装，冲突只警告不阻断。代价：不兼容是真实的——冲突的包运行时可能崩。

持久化到项目 .npmrc：

legacy-peer-deps=true

适用场景：确认 peer 冲突无害——很多库声明 peer: react@^17 但在 18 上运行良好（React 18 向后兼容 17 的 API）。React 生态里这极为常见。

策略三：overrides 精准覆盖（npm 8.3+）

强制某个传递依赖使用指定版本：

{
  "overrides": {
    "some-lib": {
      "react": "^18.2.0"
    }
  }
}

比 legacy-peer-deps 更精准——只覆盖冲突的那个包，其他依赖保持正常解析。

策略四：npm dedupe 去重

npm dedupe

通过扁平化兼容版本来减少 node_modules 中的重复。有时能把两个冲突版本合并成一个满足所有范围的版本。

千万别用 --force 的原因

npm install --force 和 --legacy-peer-deps 不同——force 会无条件安装所有包，可能在 node_modules 中产生同一包的多个版本。后果：

• 两个 React 共存 → Hooks 崩溃（"Invalid hook call"）
• 类型不兼容 → 运行时异常
• 行为不可预测

React hooks 项目永远不要用 --force——多副本 React 是 "Invalid hook call" 的头号原因。

调试工具

npm ls react              # 依赖树
npm explain some-lib      # 为什么安装了这个包
npm ls react | grep -c "react@"  # 重复版本计数

FAQ

升级 npm 后突然报 ERESOLVE，之前好好的？

npm 7 起把 peer 处理从警告改为硬性执行。npm 6 能装的项目到 7+ 就可能被阻断——不是项目坏了，是规则变了。

删 package-lock.json 重装行不行？

偶尔有效（允许传递依赖浮动到最新），但危险：所有传递依赖都可能变版本，引入新的破坏。除非同时在更新所有直接依赖，否则别这么干。

dependencies / devDependencies / peerDependencies 有什么区别？

• dependencies：运行时需要 → npm 帮你装
• devDependencies：构建/测试需要 → npm 帮你装
• peerDependencies：运行时需要宿主自己装 → npm 只检查不装

本文由 ToolVault 工具匣 提供。相关阅读：npm 换源指南、Cannot find module 修复。访问 首页 查看更多开发者工具。