npm install 报 npm ERR! code ERESOLVE / ERESOLVE unable to resolve dependency tree（peer 依赖冲突）

你会遇到什么

老前端项目（Vue2/webpack 4 时代）换电脑或换 Node 大版本后 npm install 报 ERESOLVE unable to resolve dependency tree，代码一行没动，依赖就是装不上。错误信息里其实写清楚了冲突双方（Found: ... 和 peer ... from ...）——先读报错，别急着删 node_modules。

本文路径：快速修复（30 秒一段命令）→ 一步步排查（可跳读）→ 原理与变体（症状/原因/证据）。赶时间直接跳到「快速修复」。

为什么会这样

npm 7+ 默认严格解析 peerDependencies：自动安装 peer 依赖，版本不满足直接拒绝整棵依赖树。而 npm 6 时代 peer 不匹配只是静默跳过——所以同一份 package.json 在旧 npm 上"正常"。常见触发：

• 插件版本过旧：插件声明的 peer 范围不含新版主依赖（如 eslint-plugin-import@2.22.1 的 peer 是 eslint ^2~^7.2.0，装 eslint 8 即冲突）；
• 两个依赖对同一 peer 要求互相矛盾，npm 无法同时满足；
• 换机器后 node/npm 版本变新，触发同样的解析逻辑差异。

实测环境：Node v22.22.1 / npm 9.2.0，2026-08-29。

npm 7+ 的解析器把 peerDependencies 当硬约束：安装时自动解析并安装 peer 依赖，版本不满足就拒绝整棵依赖树（ERESOLVE）；npm 6 及以前 peer 不匹配只是静默跳过（甚至不装）——同一份 package.json 在不同 npm 版本上行为不同，这是「换机器/升级后突然报错」的根因。

ERESOLVE 的常见形态：插件声明的 peer 范围太旧（不含新版主依赖）、两个依赖对同一 peer 要求互相矛盾（npm 无法同时满足）。

确定性推论：ERESOLVE 是「解析器说这套组合无解」，不是「某个包坏了」；处理优先级——升级冲突方（插件或主依赖到互相兼容的版本）> 用 overrides 显式钉住 peer 版本 > --legacy-peer-deps（退回 npm6 静默行为，最后手段）；修完 npm ls 看依赖树是否一致；

判断路径：报错信息里的 While resolving 链就是冲突双方，顺着升级。

一步步来

1. 读报错定位冲突（正解） — 排查

npm view <插件> peerDependencies

Found: ... 和 peer ... from ... 就是冲突双方。优先把插件升级到支持新版主依赖的版本，或把主依赖降回 peer 范围内。

2. 快速绕过 — 必做

npm install --legacy-peer-deps

接受旧 npm 的语义（--force 同理但更粗暴）。注意这等于接受"不正确且可能损坏"的依赖解析，装完运行时可能仍有兼容问题，只作过渡。

3. 旧项目整体重装 — 必做

删 node_modules + package-lock.json 后重装；或临时用 npm 6 语义：

npx -p npm@6 npm install --legacy-peer-deps

无需卸载 npm 7+，npx 指定版本即可（实测：本机 npm 9.2.0 vs npx npm@6 = 6.14.18）。

4. 团队默认跳过检查（治标） — 排查

项目级 .npmrc 写 legacy-peer-deps=true；长期仍建议升依赖。

怎么确认修好了

npm install --legacy-peer-deps && npm ls --depth=0

依赖树能完整装上即成功。实测：eslint@8.0.0 + eslint-plugin-import@2.22.1 → 完整复现 ERESOLVE 报错链（exit 1）；--legacy-peer-deps → added 232 packages（exit 0）；--force → 同样成功。

其它环境的表现

症状

老前端项目（Vue2/webpack 4 时代）npm install 报：

npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR! While resolving: <你的项目>@1.0.0
npm ERR! Found: <已装的主依赖>@<版本>
npm ERR! Could not resolve dependency:
npm ERR! peer <peer 名>@"<peer 版本范围>" from <插件>@<版本>

特征：换电脑/换 Node 大版本后最容易出现；项目代码没动过，但依赖就是装不上；错误信息里明确写了冲突双方（Found: ... / peer ... from ...）。

原因

npm 7+ 默认严格解析 peerDependencies：会自动安装 peer 依赖，并在版本不满足时直接拒绝整棵依赖树。而 npm 6 时代 peer 不匹配只是静默跳过不检查，所以同一份 package.json 在旧 npm 上"正常"。常见触发：

1. 插件版本过旧：插件声明的 peer 范围不含新版主依赖（如 eslint-plugin-import@2.22.1 的 peer 是 eslint ^2~^7.2.0，装 eslint 8 即冲突）；
2. 两个依赖对同一 peer 要求互相矛盾，npm 无法同时满足；
3. 换机器后 node/npm 版本变新，触发同样的解析逻辑差异。

解法

按推荐顺序选：

1. 看错误信息定位冲突，修版本（正解）：错误里的 Found: ... 和 peer ... from ... 就是冲突双方。优先把插件升级到支持新版主依赖的版本，或把主依赖降回 peer 范围内（npm view <包> peerDependencies 查范围）。
2. 快速绕过（最常用）：npm install --legacy-peer-deps —— 跳过 peer 严格检查，接受旧 npm 的语义；--force 同理但更粗暴。注意这等于接受"不正确且可能损坏"的依赖解析，装完运行时可能仍有兼容问题，只作过渡。
3. 旧项目整体重装：删 node_modules + package-lock.json 后重装；或临时用 npm 6 语义：npx -p npm@6 npm install --legacy-peer-deps（无需卸载 npm 7+，npx 指定版本即可）。
4. 若想彻底规避：项目级 .npmrc 写 legacy-peer-deps=true，让团队默认跳过检查（治标，长期仍建议升依赖）。