NPM执行install报ERESOLVE依赖冲突的解决方法

问题背景 #

在本地设备安装AWS示例demo（amazon-chime-sdk-classroom-demo）的npm依赖时，执行npm install持续抛出依赖解析错误，初步判断为本地npm、Node版本与项目要求不匹配。

完整报错信息 #

npm install
npm ERR! code ERESOLVE
npm ERR! ERESOLVE could not resolve
npm ERR! 
npm ERR! While resolving: @typescript-eslint/eslint-plugin@2.34.0
npm ERR! Found: eslint@8.4.1
npm ERR! node_modules/eslint
npm ERR!   dev eslint@"^8.4.1" from the root project
npm ERR!   peer eslint@"*" from @typescript-eslint/experimental-utils@2.34.0
npm ERR!   node_modules/@typescript-eslint/experimental-utils
npm ERR!     @typescript-eslint/experimental-utils@"2.34.0" from @typescript-eslint/eslint-plugin@2.34.0
npm ERR!     node_modules/@typescript-eslint/eslint-plugin
npm ERR!       dev @typescript-eslint/eslint-plugin@"^2.17.0" from the root project
npm ERR!       1 more (eslint-config-airbnb-typescript)
npm ERR!     @typescript-eslint/experimental-utils@"2.34.0" from @typescript-eslint/parser@2.34.0
npm ERR!     node_modules/@typescript-eslint/parser
npm ERR!       dev @typescript-eslint/parser@"^2.17.0" from the root project
npm ERR!       2 more (@typescript-eslint/eslint-plugin, eslint-config-airbnb-typescript)
npm ERR!     1 more (eslint-plugin-jest)
npm ERR!   7 more (babel-eslint, eslint-config-prettier, ...)
npm ERR! 
npm ERR! Could not resolve dependency:
npm ERR! peer eslint@"^5.0.0 || ^6.0.0" from @typescript-eslint/eslint-plugin@2.34.0
npm ERR! node_modules/@typescript-eslint/eslint-plugin
npm ERR!   dev @typescript-eslint/eslint-plugin@"^2.17.0" from the root project
npm ERR!   peer @typescript-eslint/eslint-plugin@"^2.7.0" from eslint-config-airbnb-typescript@6.3.2
npm ERR!   node_modules/eslint-config-airbnb-typescript
npm ERR!     dev eslint-config-airbnb-typescript@"^6.3.1" from the root project
npm ERR!     1 more (eslint-config-erb)
npm ERR! 
npm ERR! Conflicting peer dependency: eslint@6.8.0
npm ERR! node_modules/eslint
npm ERR!   peer eslint@"^5.0.0 || ^6.0.0" from @typescript-eslint/eslint-plugin@2.34.0
npm ERR!   node_modules/@typescript-eslint/eslint-plugin
npm ERR!     dev @typescript-eslint/eslint-plugin@"^2.17.0" from the root project
npm ERR!     peer @typescript-eslint/eslint-plugin@"^2.7.0" from eslint-config-airbnb-typescript@6.3.2
npm ERR!     node_modules/eslint-config-airbnb-typescript
npm ERR!       dev eslint-config-airbnb-typescript@"^6.3.1" from the root project
npm ERR!       1 more (eslint-config-erb)
npm ERR! 
npm ERR! Fix the upstream dependency conflict, or retry
npm ERR! this command with --force, or --legacy-peer-deps
npm ERR! to accept an incorrect (and potentially broken) dependency resolution.
npm ERR! 
npm ERR! See /Users/liycheng/.npm/eresolve-report.txt for a full report.

npm ERR! A complete log of this run can be found in:
npm ERR!     /Users/liycheng/.npm/_logs/2022-06-18T00_11_27_159Z-debug-0.log

当前环境版本 #

$ npm -v
8.9.0
$ node -v
v18.2.0

已尝试无效操作 #

执行npm install --legacy-peer-deps未解决问题。 #

根因分析 #

1. 版本适配断层：该demo是较早发布的项目，依赖链中@typescript-eslint/eslint-plugin@2.34.0仅兼容eslint 5.x/6.x版本，但本地环境拉取的根项目依赖声明了eslint 8.x版本，npm 7+版本默认开启严格peer依赖校验，直接阻断安装流程。
2. 运行时不兼容：Node 18版本与项目依赖的多个原生模块（如旧版node-sass、Chime SDK底层绑定）存在API断层，即使绕过依赖校验，后续也会出现原生模块编译失败、运行时报错的问题，这也是--legacy-peer-deps参数无效的核心原因。
3. 缓存残留：之前安装失败生成的残缺node_modules目录、package-lock.json锁文件会干扰后续安装流程的依赖解析。

分步解决方案 #

• 第一步：切换到项目适配的Node.js版本
  该项目稳定适配Node 14.x LTS版本，若本地未安装nvm，可先完成nvm安装后再执行以下版本切换操作：

  nvm install 14
  nvm use 14
  # 验证版本，确认输出为v14.x.x、npm 6.x
  node -v
  npm -v
  

• 第二步：彻底清理残留文件与缓存
  在项目根目录执行命令，清除之前安装失败产生的垃圾文件：

  rm -rf node_modules package-lock.json
  npm cache clean --force
  

• 第三步：重新安装依赖
  直接执行基础安装命令即可，无需额外参数：

  npm install
  

  若出现非阻断性的peer警告，可执行npm install --legacy-peer-deps完成安装，该操作在npm 6.x环境下可正常兼容非核心依赖冲突。
• 临时备选方案（不推荐）
  若暂时无法切换Node版本，可执行强制安装命令绕过所有校验：

  npm install --force
  

  该方式安装的依赖可能存在eslint代码检查功能失效、部分原生模块运行异常的问题，仅作临时调试使用。

注意：不要在Node 16及以上版本中长期运行该项目，除依赖冲突外，还会出现加密API不兼容、内存溢出等不可预知的运行时错误。

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