peerDependencies 是兼容性声明而非待安装包，要求宿主项目已存在指定范围的依赖；版本冲突时应调整宿主依赖而非绕过校验。
peerDependencies 不是“要装的包”，而是“必须已存在的包”
很多人一看到 peerDependencies 就下意识去 npm install，这是最典型的误解。它本质是一份**兼容性声明**：你的包（比如一个 React UI 组件库）只承诺能在某个范围的 react 版本上正常工作，但不会帮你装 react——因为宿主项目（你的业务代码）本就该决定用哪个 react 版本。
常见错误现象：
- 执行
npm install后报ERESOLVE unable to resolve dependency tree - 安装成功但运行时报
Invalid hook call或组件不渲染 -
node_modules/react出现多个副本（比如react@17.0.2和react@18.2.0并存）
根本原因不是“没装对”，而是“宿主项目装的版本和插件声明的 peerDependencies 范围不重叠”。比如插件写了 "react": ">=18.0.0"，而你项目里是 react@17.0.2，npm v7 就会直接拦住。
npm v7+ 默认自动装 peerDependencies，但会严格校验版本
npm v6 时代，peerDependencies 基本被忽略；v7 开始，它默认尝试自动安装缺失的 peer 依赖，但前提是版本能同时满足所有声明。一旦冲突，就中断安装。
关键行为差异：
-
npm install --legacy-peer-deps：退回到 v6 行为，跳过 peer 校验（适合临时调试，但别进 CI） -
npm install --force：强制覆盖、强行安装，可能破坏已有依赖树（运行时崩溃风险高） - 不加任何 flag：走 v7 默认逻辑，安全但容易卡住
性能影响很小，但兼容性检查本身会多花 1–2 秒解析依赖树。如果你的 package.json 里有多个插件都声明了 webpack，而它们要求的版本范围互斥（如一个要 "^4.0.0"，另一个要 "^5.0.0"），npm 就无法找到交集，直接报错。
真正解决问题得从宿主项目出发，不是改插件
插件作者写的 peerDependencies 是只读契约，你不能也不该去改它。解决路径永远在你的项目里：
- 运行
npm ls react（或对应 peer 包名），看实际装了几个版本、谁引入的 - 检查报错中提到的冲突包（比如
eslint-config-react-app）是否发布了支持你当前eslint版本的新版 - 如果插件还没适配，优先降级你的宿主依赖（例如把
eslint从^8.0.0改成^7.0.0），而不是升级插件到不稳定版本 - 确认
package-lock.json没被手动修改过——它决定了最终解析出的版本，手改容易导致本地和 CI 行为不一致
示例：你装 pinia@2.0 报 peer 冲突，提示需要 vue@^3.2.0，但你项目是 vue@2.7.16。这时唯一合法做法是换用 pinia@1.x，而不是加 --legacy-peer-deps 硬上——后者可能让 store 初始化失败，且错误发生在运行时，难以定位。
.npmrc 配置能统一团队行为，但掩盖不了底层不兼容
在项目根目录加 .npmrc 文件写入 legacy-peer-deps=true，确实能让所有成员免输 flag，CI 也不报错。但这只是把校验时机后移到运行时，隐患仍在。
容易被忽略的点：
- 这个配置对
yarn或pnpm完全无效，团队混用包管理器时会出问题 - CI 环境若缓存了旧版
node_modules，可能跳过重新解析，导致看似通过实则漏检 - 某些插件（如 webpack loader）会在构建期动态 require peer 包，版本错位会导致
Cannot find module 'xxx'这类运行时报错，而非安装时报错
真正复杂的点在于：peer 依赖往往嵌套多层。比如 A 插件依赖 B，B 声明了 peerDependencies: { vue: '^3.0.0' }，而 A 又没显式声明，你查 npm ls vue 可能只看到 A 的路径，却漏掉 B 的约束。这时候必须用 npm ls -a vue 查全量依赖树。
