npm install --legacy-peer-deps：它到底做了什么，什么时候该用？

为什么总是说：加上 --legacy-peer-deps 就好了呢？

如果经常在前端项目中用 npm 装包，大概见过这样的场景：

npm install

然后报错：

ERESOLVE unable to resolve dependency tree

接着在网上搜解决方法，大家都说：

npm install --legacy-peer-deps

执行后，居然装成功了！

但问题是：

1. 为什么它能解决？2. 会不会有副作用？3. 到底什么时候该用？

下面从 npm 的依赖机制讲起。

1. 理解 npm 的依赖关系体系

在 npm 中，包的依赖主要分为三种类型：

类型	定义	示例
dependencies	项目运行时需要的包	vue，axios
devDependencies	仅开发阶段需要的包	eslint，vite
peerDependencies	用于声明“我需要和宿主共用同一个依赖版本”	比如一个 Vue 插件依赖 vue

举个 🌰

{"name": "my-plugin","peerDependencies": {"vue": "^3.2.0"}
}

意思是：“我（my-plugin）不安装 vue，但（使用我的项目）必须已经安装了与我兼容的 vue。”

2. npm 7+ 的重大变化

在 npm 6 及以前，peerDependencies 只是一个提示，不会自动安装。如果用户没装对版本，最多会警告。

但从 npm 7 开始（Node.js 15.0+ 自带），npm 改变了行为：npm 现在会自动安装 peerDependencies，并且严格校验版本号，如果有冲突，直接报错。

这就是“ERESOLVE unable to resolve dependency tree”的根源。

举个 🌰

假设项目依赖：

{"dependencies": {"react": "^18.0.0","react-dom": "^18.0.0","antd": "^5.0.0"}
}

而 antd@5.0.0 的 peerDependencies 是：

"peerDependencies": {"react": ">=16.9.0 <18.0.0"
}

于是冲突：你的项目用了 React 18，但 antd 只支持 <18

npm7+ 会报错：ERESOLVE unable to resolve dependency tree。

3. --legacy-peer-deps 是什么？

--legacy-peer-deps 是 npm 提供的一个选项，用来让安装行为回退到 npm v6 的旧逻辑。

也就是说：

⚙️ 不要去自动安装 peerDependencies，也不要去严格校验它们的版本冲突。

换句话说：

• 忽略 peerDependencies 冲突；

• 照旧安装所有依赖；

• 不中断整个安装流程。

对比一下

行为	npm 6 (旧逻辑)	npm 7+ (新逻辑)	加上 --legacy-peer-deps
自动安装 peerDependencies	不安装	自动安装	不安装
检查版本冲突	仅警告	报错终止	忽略冲突
安装成功率	高	容易失败	高

4. 怎么使用？

最常见的用法就是在安装时加上这个参数：

npm install --legacy-peer-deps

或者安装单个依赖时：

npm install eslint --legacy-peer-deps

或者全局命令：

npm ci --legacy-peer-deps

应用场景

1、老项目迁移 / 依赖复杂的项目

比如老 Vue 2 + Webpack 4 的项目，有很多老旧插件，npm i 经常各种依赖冲突。

2、公司内部私有包 / 未及时更新的插件

如果你的项目依赖了内部封装的 npm 包，这些包声明的 peerDependencies 版本不一致，
npm 会卡住不让装。

临时解决：npm install --legacy-peer-deps

但需要注意：虽然这个命令“能让项目跑起来”，但它不是万能钥匙。

和 --force 的区别

命令	含义	安装结果
--force	强制重新下载并覆盖所有包	粗暴但危险
--legacy-peer-deps	忽略 peerDependencies 冲突	相对安全

总结一句：

--legacy-peer-deps 是“忽略版本冲突”；--force 是“忽略一切风险”。

总结：

问题	说明
命令作用	忽略 peerDependencies 校验，按旧逻辑安装依赖
什么时候用	当依赖冲突但又必须先安装成功时
为什么有用	npm 7+ 改变了依赖解析逻辑，引入严格检查
风险	可能装入不兼容版本，建议仅作临时方案