Heroku部署React应用出现npm ERESOLVE依赖冲突报错求助

问题现象 #

在Heroku平台部署react app时触发依赖安装错误，删除package-lock.json后重新执行npm install仍复现问题。

当前项目依赖配置 #

"dependencies": {
    "@emotion/react": "^11.9.0",
    "@emotion/styled": "^11.8.1",
    "@material-ui/core": "^4.12.4",
    "@mui/icons-material": "^5.8.3",
    "@mui/material": "^5.8.3",
    "@testing-library/jest-dom": "^5.16.4",
    "@testing-library/react": "^13.1.1",
    "@testing-library/user-event": "^13.5.0",
    "axios": "^0.27.2",
    "cors": "^2.8.5",
    "express": "^4.18.1",
    "multer": "^1.4.4",
    "mysql2": "^2.3.3",
    "path": "^0.12.7",
    "react": "^18.0.0",
    "react-dom": "^18.0.0",
    "react-hook-form": "^7.31.2",
    "react-router-dom": "^6.3.0",
    "react-scripts": "^5.0.1",
    "react-tweet-embed": "^2.0.0",
    "sequelize": "^6.20.1",
    "web-vitals": "^2.1.4"
  },

部署报错日志 #

-----> Installing binaries
       engines.node (package.json):  unspecified
       engines.npm (package.json):   unspecified (use default)
       
       Resolving node version 16.x...
       Downloading and installing node 16.15.1...
       Using default npm version: 8.11.0
       
-----> Installing dependencies
       Installing node modules
       npm ERR! code ERESOLVE
       npm ERR! ERESOLVE could not resolve
       npm ERR! 
       npm ERR! While resolving: @material-ui/core@4.12.4
       npm ERR! Found: react@18.1.0
       npm ERR! node_modules/react
       npm ERR!   react@"^18.0.0" from the root project
       npm ERR!   peer react@">= 16" from react-scripts@5.0.1
       npm ERR!   node_modules/react-scripts
       npm ERR!     react-scripts@"^5.0.1" from the root project
       npm ERR!   16 more (@mui/utils, react-router-dom, @emotion/react, ...)
       npm ERR! 
       npm ERR! Could not resolve dependency:
       npm ERR! peer react@"^16.8.0 || ^17.0.0" from @material-ui/core@4.12.4
       npm ERR! node_modules/@material-ui/core
       npm ERR!   @material-ui/core@"^4.12.4" from the root project
       npm ERR! 
       npm ERR! Conflicting peer dependency: react@17.0.2
       npm ERR! node_modules/react
       npm ERR!   peer react@"^16.8.0 || ^17.0.0" from @material-ui/core@4.12.4
       npm ERR!   node_modules/@material-ui/core
       npm ERR!     @material-ui/core@"^4.12.4" from the root project
       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 /tmp/npmcache.MrETS/eresolve-report.txt for a full report.

报错根因 #

核心为peer依赖版本不兼容：

1. 项目使用React 18.x版本，但旧版@material-ui/core@4.12.4仅支持React 16.8.x/17.x版本，npm 8.x默认开启严格peer依赖校验，匹配失败会直接终止安装。
2. 项目package.json未指定Node、npm版本，Heroku部署时拉取默认版本，会进一步放大依赖兼容不确定性。

修复方案 #

• 优先方案（长期稳定）：统一MUI依赖版本
  项目中已经安装了完全兼容React 18的MUI 5.x版本（@mui/material、@mui/icons-material），直接卸载冲突的旧版包即可：
  npm uninstall @material-ui/core
  后续将代码中所有引用@material-ui/core的部分替换为@mui/material的对应API，从根源消除版本冲突。
• 快速方案（临时上线用）：跳过peer依赖严格校验
  配置部署参数绕过npm的严格校验，两种实现方式二选一即可：
  1. 在项目根目录新建.npmrc文件，写入legacy-peer-deps=true，提交到代码仓库。
  2. 在package.json中补充engines配置锁定Node/npm版本，固定部署环境减少兼容问题：

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

  注意该方案存在潜在运行时兼容风险，上线后需要回归所有Material UI相关页面功能。
• 备选方案：降级React版本到兼容区间
  如果必须保留@material-ui/core@4.12.4，可将React、react-dom降级到17.0.2匹配依赖要求：
  npm install react@17.0.2 react-dom@17.0.2
  降级后需要验证React Router 6等其他依赖是否兼容React 17，避免出现运行时错误。

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