如何使用 –legacy-peer-deps 避免 npm 依赖冲突：基于 Fishcoderman 项目的详细解析

--legacy-peer-deps 的确可以让你绕过 peerDependencies 的冲突报错，但许多人并不清楚：那最终到底安装的是哪个版本？它是怎么决定的？

下面我用一个完整的例子来帮你说明 --legacy-peer-deps 生效时，npm 是如何解析并选择最终安装的版本的。

✅ 先理解：`--legacy-peer-deps` 做了什么

跳过 peerDependencies 的 冲突检查；
不自动安装 peerDependencies；
更像 npm v6 的行为：只根据 dependencies 来安装。

换句话说，安装什么版本由 直接依赖的声明 和 依赖的 dependencies 决定，而不再理会 peerDependencies 声明冲突是否会造成不一致。

🧪 举个例子：两个包有冲突的 peerDependency

假设：

你的项目依赖两个包 a 和 b；
a 的 peerDependencies 要求 react@^17.0.0
b 的 peerDependencies 要求 react@^18.0.0

你的 package.json 中写的是：

{
  "dependencies": {
    "a": "1.0.0",
    "b": "1.0.0",
    "react": "^18.2.0"
  }
}

这在 npm v7+ 默认行为下会报错（peer 冲突）：

ERESOLVE could not resolve dependency
peer react@"^17.0.0" from a@1.0.0
peer react@"^18.0.0" from b@1.0.0

✅ 使用 `--legacy-peer-deps` 安装：

npm install --legacy-peer-deps

此时：

NPM 忽略了 peerDependencies 的冲突
只根据你在 package.json 中直接声明的 "react": "^18.2.0" 安装
所以最终安装的是：react@18.2.x 最新稳定版本

🧠 再举个没有声明 react 的例子（更重大）

你没在项目中声明 react，只是这样：

{
  "dependencies": {
    "a": "1.0.0",
    "b": "1.0.0"
  }
}

依旧：

a 要求：peerDependencies: { react: ^17.0.0 }
b 要求：peerDependencies: { react: ^18.0.0 }

使用默认安装：

npm install

❌ 会报错，由于 npm 无法判断该装哪个版本的 react（两边冲突）。

使用：

npm install --legacy-peer-deps

✅ npm 会：

不报错；
也不会自动安装 react；
a 和 b 都装了，但它们的 peerDependencies 未被满足，你自己必须手动安装一个 react。

你接着运行：

npm install react@18.2.0

最终：

项目装的是 react@18.2.0
b 满意
a 不满足（但你跳过了检查，所以能运行但可能报错）

📌 总结重点

场景	安装行为
使用 –legacy-peer-deps	忽略 peerDependencies 冲突，装你写的版本
没写依赖时	不会自动安装任何 peerDependency
安装哪个版本？	由你项目中 dependencies 指定的为准
是否合理？	有风险，列如 a 运行时找不到 react@17

如你有实际依赖报错的项目，可以贴出 a、b、react 的版本和依赖关系，我可以帮你分析会装哪个版本及是否稳定运行。

超级好的问题！`–legacy-peer-deps` 的确可以让你绕过 `peerDependencies` 的冲突报错，但许多人并不清楚：**那最终到底安装的是哪个版本？它是怎么决定的？**