Azure DevOps构建时npm ERESOLVE peer依赖冲突解决方法

API 探路者

2026-8-28

问题根因

该错误仅在Azure DevOps构建管道触发、本地运行无报错的核心原因是环境npm版本差异：

本地环境使用npm v6及更早版本，这类版本对peer依赖冲突仅输出警告，不会中断安装流程
Azure构建环境默认使用npm v7及以上版本，从v7开始npm默认开启严格peer依赖校验，依赖树中peer版本要求不匹配时会直接抛出ERESOLVE错误终止安装
你遇到的冲突本质是@wtw/chart@1.3.0的peer依赖声明存在错误：其声明的peer依赖@wtw/common@"^0.0.0"是无效版本范围，无法匹配项目中使用的@wtw/common@1.4.0。尝试将@wtw/common降级到0.0.0会触发旧版本包与Angular 12的版本冲突，且你无@wtw私有包的修改权限，无需调整现有业务依赖版本。

解决方案（按推荐优先级排序）

方案1：对齐本地npm依赖处理逻辑（最稳妥，零业务风险）
让CI环境的npm安装行为和本地完全一致，跳过严格peer依赖校验即可：
1. 临时生效：修改Azure DevOps管道中的npm安装命令，添加--legacy-peer-deps参数：
```
npm install --legacy-peer-deps
```
2. 永久生效：在项目根目录新建.npmrc文件提交到代码库，所有环境执行npm安装时自动应用配置，无需每次修改命令：
```
legacy-peer-deps=true
```
该配置完全复现npm v6的依赖处理逻辑，和你本地当前的运行状态完全对齐，不会引入额外兼容性问题。
方案2：通过overrides强制对齐依赖版本（保留npm严格校验能力）
如果需要保留npm v7+的严格依赖校验特性，可在项目package.json中新增overrides字段，强制所有包引用的@wtw/common使用根项目声明的版本，绕过@wtw/chart错误的peer依赖声明：
```
{
  "dependencies": {
    // 原有dependencies配置保持不变
  },
  "overrides": {
    "@wtw/chart": {
      "@wtw/common": "$@wtw/common"
    }
  }
}
```
配置中$@wtw/common表示自动引用根项目dependencies中声明的@wtw/common版本，后续升级根依赖时无需同步修改override配置。

注意：不推荐使用npm install --force参数强制安装，该参数会跳过所有依赖校验逻辑，可能引入隐式的版本不兼容问题，风险远高于上述两种方案。

额外排查项

如果应用上述配置后仍报错，检查Azure管道是否开启了npm依赖缓存，可在install步骤前添加缓存清理命令，避免旧的错误缓存导致安装失败：

npm cache clean --force

内容的提问来源于stack exchange，提问作者fritz6