现象
把项目里的 ReaCt 升到 18 后执行 npm install,npm 10.5 直接报 ERESOLVE unable to resolve dependency tree,提示某个 UI 库的 peer 依赖还要求 React 17,安装中断。删掉 node_modules 和 package-lock.json 重装,报错一字不差。
原因
npm 7 之后默认严格校验 peerDependencies,依赖树里出现两个互斥的版本要求就拒绝安装,而不是像 npm 6 那样只打警告。多数情况是某个老依赖还没适配新版本,属于上游没跟上,与网络和缓存无关。
解决步骤
第一步,先看冲突链路。报错里会打印 Found 和 Could not resolve 两段,配合下面命令定位是哪个包要求旧版本。
npm ls react
npm explain react
npm install --legacy-peer-deps
第二步,评估用 --legacy-peer-deps 还是 --force。前者只跳过 peer 校验,保留原有解析规则,适合老项目临时过渡;--force 会覆盖冲突,风险更高,只在确认无运行时影响时使用,两者都建议当作临时手段。
第三步,根治是替换或升级冲突包。查该依赖的更新版本是否已支持 React 18,能升就升;不能升就找替代库,或在 peerDependenciesMeta 里把它标记为 optional 并放宽版本范围。
验证
去掉临时参数重新 npm install 能完整通过,npm ls react 只显示一个 18.x 版本,构建和页面渲染正常,说明依赖树已经收敛。
小结
ERESOLVE 是 peer 依赖打架的提示,不是安装器坏了。先用 npm explain 找源头,再决定临时跳过还是替换包。
