A 依赖 C v1.0
B 依赖 C v2.0
项目同时使用 A 和 B，就有依赖冲突问题。
到底是用 C v1.0 还是 C v2.0？
在 npm 7 之前(不包含 npm7)，安装规则如下：
• peerDependencies 仅声明，不自动安装。例如，一个 React 组件库在 peerDependencies 字段声明需要 react@^17.0.0，npm install 时不会自动安装 react@^17.0.0，需要开发者手动安装。
• 冲突时仅输出警告。若项目已安装版本与包的 peerDependencies 声明不兼容，安装过程不会中止，仅在控制台输出警告。
• 扁平化依赖结构。默认采用扁平化安装策略，将依赖尽可能提升至项目根 node_modules 下。当版本冲突无法避免时，会将特定版本嵌套安装在子级 node_modules 中，此策略可能导致依赖路径解析异常和难以追踪的版本不一致问题。
|-- myapp
|-- node_modules
|-- A
|-- node_modules
|-- C v1.0
|-- B
|-- C v2.0
从 npm 7 开始，依赖管理变得严格得多：
• 自动安装 peerDependencies。npm install 会尝试自动安装满足对等依赖声明要求的包。
• 冲突即安装失败。如果多个包对同一个 peerDependencies 声明了无法兼容的版本范围（例如 react@^17.0.0 与 react@^18.0.0），npm install 会因无法构建有效的依赖树而直接失败，抛出 ERESOLVE 错误。
• 精确依赖树与 lockfile。构建更精确的支持嵌套结构的依赖树，package-lock.json 格式随之更新，以支持确定性、可复现的构建，并开始兼容读取 yarn.lock 文件。
• 内置 Workspaces 支持。原生支持单仓库多包（monorepo）管理模式。
--legacy-peer-depsnpm 7+ 的严格性在升级旧项目或使用尚未更新声明的第三方库时，常常导致安装失败。
为此 npm 提供了 --legacy-peer-deps 选项作为过渡方案，该参数指示 npm 回退到 npm 6 的行为模式——即不自动安装 peerDependencies，并忽略版本冲突，仅输出警告，不中断安装。
可以直接在安装命令里加参数:
$ npm install --legacy-peer-deps
或者在 .npmrc 文件中启用配置:
// .npmrc
legacy-peer-deps=true
注意📢：长期依赖此选项会掩盖真正的依赖问题，阻碍项目依赖结构的健康化和升级路径，这只是一种临时手段。
在 package.json 中配置 overrides 字段，可强制指定某个包在整个依赖树中的版本。npm (v7+ 支持完善) 会确保所有依赖都使用你指定的版本，无论其原始声明如何。
示例配置:
{
"overrides": {
// 基础用法：全局覆盖某个包
"lodash": "4.17.21",
// 引用顶层依赖的版本（推荐用于统一核心库）
"react": "$react",
"react-dom": "$react-dom",
// 嵌套覆盖：只覆盖特定包下的子依赖
"some-package": {
"axios": "1.6.0"
},
// 使用路径语法进行精确覆盖
"parent-package>child-package": "2.0.0"
}
}
配置后，需要删除 node_modules 和 package-lock.json，然后重新执行 npm install 以使覆盖生效。
一个常见的疑惑是：既然 npm 7+ 会自动安装 peerDependencies，为什么不直接将它们写入 dependencies？
• 写入 dependencies。假设你开发一个 React 组件库并将 react 列入 dependencies。用户安装你的库时，npm 会在库自身的 node_modules 下安装一份 React。这会导致用户项目根 node_modules 和库的 node_modules 中各有一份 React，可能引发严重的运行时错误（如 Hooks 规则破坏、Context 失效），因为应用可能加载了不同版本的 React 实例。
|-- myapp
|-- node_modules
|-- my-components
|-- node_modules
|-- react // 依赖写在 dependencies 里，会在库自身的 node_modules 下安装 React
|-- react // 用户项目根 node_modules 下安装 React
• 写入 peerDependencies。声明你的库兼容 react@^17.0.0。当用户项目已安装 react@18.0.0 时，npm 会检测到版本兼容（^17.0.0 兼容 18.0.0），不会在库下重复安装 React，而是让库直接共享项目提供的单一 React 实例，从而根治了“多副本”问题。
• peerDependencies 的严格性。npm 7+ 会强制解决冲突。若多个包对同一 peerDependencies 的版本要求存在不可调和的冲突，安装会立即失败，迫使开发者直面并解决兼容性问题，确保了依赖树的长期健康。
• dependencies 的共存策略。若冲突发生在 dependencies，npm 会默认尝试让不同版本共存。例如，包 A 依赖 lodash@^4.17.0，包 B 依赖 lodash@^5.0.0，npm 可能在根目录安装 v5.0.0，同时在包 A 的本地 node_modules 中安装 v4.17.21 以满足其要求。虽然安装成功，但可能导致包 A 和包 B 因使用不同主版本的 lodash 而产生隐性的行为不一致问题。
↶ 返回首页 ↶