Docker构建执行npm ci报Conflicting peer dependency如何解决

问题根因 #

npm ci 严格依据lock文件安装依赖的特性，不会跳过npm v7及以上版本默认开启的peer依赖强校验逻辑：只要依赖树中存在声明不匹配的peer依赖，哪怕lock文件中已经锁定了所有依赖版本，也会在安装前的校验阶段直接抛出冲突报错，终止构建流程。
你本地执行npm install --force可以绕过，本质是加了参数让npm跳过了这层校验，这个逻辑对npm ci同样适用。

按优先级选择修复方案 #

• 最高优先级（和本地行为完全对齐，无额外副作用）：直接修改Dockerfile中的安装命令，给npm ci加上和本地install一致的强制参数即可：

  RUN npm ci --force
  

  该命令会严格按照lock文件锁定的版本安装依赖，不会修改lock文件，仅跳过peer依赖冲突校验，和你本地强制安装的行为完全一致。
• 兼容性优先方案：如果担心--force行为过于激进，可以替换为npm v6风格的peer解析参数：

  RUN npm ci --legacy-peer-deps
  

  该参数会关闭npm v7+新增的peer依赖自动安装、强校验逻辑，采用旧版解析规则，对老项目的兼容性更好，出现未知安装问题的概率更低。

常见触发原因排查 #

如果加参数后仍有异常，可以对照以下场景定位问题：

1. 本地与Docker镜像内的npm版本不一致：npm v7、v8、v9三个大版本的peer校验逻辑存在差异，比如本地用npm 6不会做peer强校验，生成的lock文件自带冲突，到镜像内用高版本npm构建就会触发报错。可以在Dockerfile的依赖安装命令前加一行RUN npm -v打印版本，和本地执行npm -v的结果对齐，能解决大部分版本差异导致的异常。
2. 本地lock文件未同步提交：很多人本地执行npm install --force后，只提交了package.json的变更，没有把重新生成的package-lock.json提交到代码仓库，导致Docker构建时拉取到的lock文件本身存在依赖树冲突，自然会校验失败。本地删除node_modules和旧lock文件，重新执行强制安装后提交新的lock文件即可。
3. 不要用npm install替换npm ci做构建：install命令会自动升级符合semver范围的依赖版本，可能导致构建结果和本地环境不一致，失去npm ci版本锁定、安装速度快的优势，不推荐在生产构建场景使用。

提示：上述参数方案均为绕过校验的快速修复手段，peer依赖冲突本身代表依赖版本存在不兼容的可能性，空闲时建议排查对应依赖的版本要求，升级到官方兼容的版本从根源解决问题，避免运行时出现诡异的兼容bug。

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