Docker构建React应用时报ERESOLVE依赖冲突错误无法解决

问题场景 #

执行docker镜像构建命令：

docker build -t dashboard:latest .

构建过程中抛出依赖解析错误：

code ERESOLVE

#9 83.73 npm ERR! ERESOLVE unable to resolve dependency tree
#9 83.73 npm ERR! 
#9 83.73 npm ERR! While resolving: react-berry-admin-template@0.0.4
#9 83.73 npm ERR! Found: react@17.0.2
#9 83.73 npm ERR! node_modules/react
#9 83.74 npm ERR!   react@"^17.0.2" from the root project
#9 83.74 npm ERR! 
#9 83.74 npm ERR! Could not resolve dependency:
#9 83.74 npm ERR! peer react@"^0.14.0 || ^15.0.0 || ^16.0.0" from react-custom-scrollbars@4.2.1
#9 83.74 npm ERR! node_modules/react-custom-scrollbars
#9 83.74 npm ERR!   react-custom-scrollbars@"^4.2.1" from the root project
#9 83.74 npm ERR! 
#9 83.74 npm ERR! Fix the upstream dependency conflict, or retry
#9 83.74 npm ERR! this command with --force, or --legacy-peer-deps
#9 83.74 npm ERR! to accept an incorrect (and potentially broken) dependency resolution.

本地执行npm install --save --legacy-peer-deps后问题未解决。

本地执行带参数的安装命令仅对本地环境生效，docker构建是在隔离容器环境内执行依赖安装，既不会复用本地的node_modules目录，也不会继承本地npm命令的参数，容器内默认还是执行原生npm install，严格校验peer依赖自然会报错。
具体冲突点是react-custom-scrollbars@4.2.1已经停止维护多年，官方版本的peer依赖声明仅支持React 14/15/16版本，和项目使用的React 17版本不匹配，npm 7及以上版本默认开启严格peer依赖校验，检测到冲突就会直接终止安装流程。

按推荐优先级选择即可：

• 方案一：替换维护中的兼容包（无后续隐患，优先选择）
  原包react-custom-scrollbars已经无人维护，直接替换为社区维护的兼容fork版本react-custom-scrollbars-2，API和原包完全对齐，原生支持React17/18：

  1. 本地卸载原包：

  npm uninstall react-custom-scrollbars
  

  2. 安装兼容版本：

  npm install react-custom-scrollbars-2
  

  3. 全局替换项目内的引入路径，把所有from 'react-custom-scrollbars'改为from 'react-custom-scrollbars-2'，其余业务代码不需要调整。
     改完直接重新执行docker构建命令即可。

• 方案二：修改Dockerfile跳过依赖校验（最快，适合临时跑通流程）
  直接修改项目根目录的Dockerfile，找到里面执行npm安装的行，加上--legacy-peer-deps参数：

  # 把原来的RUN npm install 或者 RUN npm ci替换为下面的内容
  RUN npm install --legacy-peer-deps
  

  注意npm ci不支持该参数，必须替换为npm install，改完直接重新构建即可。

  风险提示：该方案是强制跳过依赖校验，如果原包用到React17中删改的API，运行时可能出现未知bug，仅适合临时验证场景使用。

• 方案三：通过overrides配置强制指定依赖版本
  不想换包也不想修改安装参数的话，可以直接在项目package.json中添加overrides字段，告诉npm忽略原包的peer依赖声明，强制使用项目内指定的React版本：

  {
    "overrides": {
      "react-custom-scrollbars": {
        "react": "^17.0.2",
        "react-dom": "^17.0.2"
      }
    }
  }
  

  添加完成后本地重新执行npm install更新lock文件，再重新构建镜像即可。

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