Heroku推送被拒 Node.js应用编译失败 ERESOLVE依赖冲突报错

Heroku构建环境默认使用npm 8.x版本，该版本默认开启严格的peer依赖校验。项目中使用的react-typical@0.1.3包声明仅支持React 15.x/16.x版本，与项目安装的react@17.0.2版本不匹配，触发ERESOLVE依赖解析错误，导致heroku-postbuild脚本执行失败，最终推送被拒。
同时项目package.json中未指定Node/npm版本，存在后续构建环境默认版本升级引发未知问题的隐患。

方案1：替换兼容包（最稳妥，无运行时风险） #

• 进入client目录执行命令卸载不兼容的包：npm uninstall react-typical
• 更换为支持React 17+版本的同类打字动效包，参照新包的文档替换原有组件的调用逻辑即可，从根源消除依赖冲突。

方案2：跳过peer依赖严格校验（快速修复，改动量最小） #

react-typical@0.1.3实际在React 17环境下可正常运行，仅未更新peer依赖声明，可通过配置npm跳过严格校验完成构建：

注意：--legacy-peer-deps参数仅让npm沿用v6版本的依赖解析逻辑、跳过严格peer依赖校验，不会篡改实际安装的包版本，绝大多数场景下不会引发运行时异常。

• 打开项目根目录的package.json文件，找到scripts配置项中的heroku-postbuild字段，原配置为：

"heroku-postbuild": "NPM_CONFIG_PRODUCTION=false npm install --prefix client && npm run build --prefix client"

• 给client端依赖安装命令添加--legacy-peer-deps参数，修改后配置为：

"heroku-postbuild": "NPM_CONFIG_PRODUCTION=false npm install --prefix client --legacy-peer-deps && npm run build --prefix client"

• （可选）如果本地安装client端依赖也报相同错误，可在client目录下新建.npmrc文件，写入如下配置，后续本地、线上安装依赖都会自动跳过peer依赖严格校验，无需每次手动加参数：

legacy-peer-deps=true

额外优化：锁定运行时版本 #

在根目录package.json中添加engines字段，指定与本地开发环境一致的Node/npm版本，避免Heroku后续升级默认版本导致构建异常，参考配置：

"engines": {
  "node": "16.16.0",
  "npm": "8.11.0"
}

修改完成后重新提交代码推送到Heroku即可完成部署。

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