npm install 卡在 ERRESOLVE / peer dependency 冲突时，有人会直接甩 --legacy-peer-deps。它能装上，但也可能把「版本对不齐」藏起来。本文说明它在干什么、什么时候能用、怎样验证没有埋雷。
你遇到的问题（现象）
典型报错类似：
npm ERR! code ERESOLVE
npm ERR! ERESOLVE could not resolve
npm ERR! peer dep missing: react@^18, found react@19
或某个插件声明只支持旧版框架，和你当前主版本冲突。
2 分钟诊断
问三件事：
- 冲突的 peer 是谁？ 读报错里的
peer与found。 - 有没有官方兼容版本？ 升级/降级一方能否消掉冲突。
- 是临时脚手架，还是要长期维护的生产依赖？ 后者慎用绕过。
--legacy-peer-deps 在干什么
npm v7+ 默认会严格校验 peerDependencies。加了 --legacy-peer-deps 后，安装行为更接近 npm v6：不再因 peer 冲突直接失败，继续装你声明的依赖树。
它不是：
- 自动修好版本兼容
- yarn/pnpm 的同名开关（包管理器各有策略；pnpm 更严，更不该习惯性绕过）
解法选型
| 情况 | 建议 |
|---|---|
| 有明确兼容的版本组合 | 对齐版本（优先），不要加 flag |
| 上游包 peer 声明过时，社区确认可跑 | 可临时 --legacy-peer-deps，并开 issue/跟进升级 |
| 新项目刚脚手架、只想先跑起来 | 可临时使用，随后删掉并修 package |
| 生产核心链路、版本敏感（React 大版本等） | 不要长期依赖该 flag |
用法
单次：
npm install --legacy-peer-deps
项目级（谨慎）：
npm config set legacy-peer-deps true
# 或在项目 .npmrc 写入：legacy-peer-deps=true
更好的长期做法：
# 先尝试找兼容版本
npm view <pkg> peerDependencies
然后调整 package.json 使 peer 区间重叠。
如何验证
-
npm install（或 CI）在不依赖隐藏配置时也能过，或文档标明必须 legacy 的原因 - 应用能启动；与冲突相关的功能（UI 库、路由、插件）烟雾测试通过
- 锁定文件已提交；团队其他人干净安装可复现
- 若用了
.npmrc，README 写明「为何」和「何时删除」
常见坑
- 全局打开
legacy-peer-deps后所有项目都「假绿」 - 用 yarn/pnpm 却去搜 npm flag：应对齐当前包管理器的 peer 策略
- 冲突来自重复安装的多份 React：先查
npm ls react，不一定是 legacy 能解决的
下一步
- 把报错里的 peer 双方记下来，先查有没有兼容版本。
- 只有确认无兼容组合时，再临时加
--legacy-peer-deps。 - 开一张后续票：升级依赖并删掉 legacy 配置。