Heroku部署Next.js报npm ERESOLVE依赖错误致构建失败

问题现象 #

在Heroku平台执行项目构建部署时触发依赖安装失败，项目此前可正常完成构建，本次无代码改动情况下突发异常，核心报错为npm ERESOLVE could not resolve，构建日志关键信息如下：

remote:        npm ERR! code ERESOLVE
remote:        npm ERR! ERESOLVE could not resolve
remote:        npm ERR! While resolving: next@12.1.6
remote:        npm ERR! Found: react@16.14.0
remote:        npm ERR! Could not resolve dependency:
remote:        npm ERR! peer react@"^17.0.2 || ^18.0.0-0" from next@12.1.6

根本原因 #

• 直接原因是依赖版本硬性冲突：项目根目录声明的react版本范围为^16.10.1，实际安装版本为react@16.14.0，但项目依赖的next@12.1.6明确要求peer依赖react版本满足^17.0.2 || ^18.0.0-0，两个版本范围完全不重叠；同时项目使用的旧版react-apollo@3.1.5仅支持react@^16.8.0，和高版本react也存在兼容问题，形成依赖锁死。
• 无改动突发报错的核心诱因是Heroku构建环境的npm版本默认升级到v7及以上：npm v7版本开始默认开启严格peer依赖校验，遇到版本不匹配直接阻断安装流程；此前构建环境使用npm v6时，同类peer依赖冲突只会输出警告不会中断构建，因此即使依赖版本存在不匹配也能正常完成部署。

可行解决方案 #

按优先级从高到低排列：

• 依赖版本对齐（长期最优方案）
  二选一即可：
  1. 降级Next.js到兼容React 16的版本：将package.json中next的版本号修改为"11.1.4"，删除版本号前的^前缀避免自动拉取新高版本，重新触发部署即可。Next.js 11是官方最后一个支持React 16的稳定大版本，和现有React 16、旧版react-apollo生态完全兼容。
  2. 全量升级React生态：将react、react-dom升级到17.0.2版本，同时将已停止维护的react-apollo依赖替换为官方维护的@apollo/client（3.x版本完整支持React 17），完成相关API适配后再部署。
• 兼容旧构建逻辑（快速修复，无业务代码改动）
  两种配置二选一即可跳过严格peer依赖校验，回到此前npm v6的构建逻辑：
  1. 在Heroku项目后台设置环境变量NPM_CONFIG_LEGACY_PEER_DEPS=true，重新触发构建。
  2. 在package.json中新增engines字段指定npm使用6.x版本，配置示例：

     "engines": {
       "npm": "6.x"
     }
     

  该方案可以在不改动现有依赖的情况下快速恢复部署，注意该方案只是绕过校验，没有解决实际的版本兼容问题，后续做依赖升级时仍需处理版本冲突。
• 强制安装（不推荐，仅极端救急使用）
  配置Heroku构建时执行npm install --force强制跳过所有依赖校验直接安装，该方案比--legacy-peer-deps逻辑更激进，有很高概率出现运行时兼容报错，非紧急情况不要使用。

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