使用Google Maps API的React MERN应用Heroku部署失败排查

问题背景 #

因课程作业需求，尝试将集成Google Maps API相关依赖的React MERN栈应用部署至Heroku平台，部署过程中构建失败，多次尝试排查仍未解决问题。

Heroku报错信息 #

Total 13 (delta 9), reused 0 (delta 0), pack-reused 0
remote: Compressing source files... done.
remote: Building source:
remote: 
remote: -----> Building on the Heroku-20 stack
remote: -----> Determining which buildpack to use for this app
remote: -----> Node.js app detected
remote:        
remote: -----> Creating runtime environment
remote:        
remote:        NPM_CONFIG_LOGLEVEL=error
remote:        NODE_VERBOSE=false
remote:        NODE_ENV=production
remote:        NODE_MODULES_CACHE=true
remote:        
remote: -----> Installing binaries
remote:        engines.node (package.json):  16.x
remote:        engines.npm (package.json):   unspecified (use default)
remote:        Resolving node version 16.x...
remote:        Downloading and installing node 16.16.0...
remote:        Using default npm version: 8.11.0
remote:        
remote: -----> Installing dependencies
remote:        Installing node modules
remote:        npm ERR! code ERESOLVE
remote:        npm ERR! ERESOLVE could not resolve
remote:        npm ERR! While resolving: @reach/combobox@0.16.5
remote:        npm ERR! Found: react@18.2.0
remote:        npm ERR! node_modules/react
remote:        npm ERR!   react@"^18.2.0" from the root project
remote:        npm ERR!   peer react@"^16.8 || ^17 || ^18" from @react-google-maps/api@2.12.0
remote:        npm ERR!   node_modules/@react-google-maps/api
remote:        npm ERR!     @react-google-maps/api@"^2.12.0" from the root project
remote:        npm ERR!   9 more (@testing-library/react, react-avatar, react-dom, ...)
remote:        npm ERR! Could not resolve dependency:
remote:        npm ERR! peer react@"^16.8.0 || 17.x" from @reach/combobox@0.16.5
remote:        npm ERR! node_modules/@reach/combobox
remote:        npm ERR!   @reach/combobox@"^0.16.5" from the root project
remote:        npm ERR! 
remote:        npm ERR! Conflicting peer dependency: react@17.0.2
remote:        npm ERR! node_modules/react
remote:        npm ERR!   peer react@"^16.8.0 || 17.x" from @reach/combobox@0.16.5
remote:        npm ERR!   node_modules/@reach/combobox
remote:        npm ERR!     @reach/combobox@"^0.16.5" from the root project

问题初步排查结论 #

从报错日志可见，依赖安装阶段npm抛出ERESOLVE依赖解析错误：项目使用React 18.2.0版本，但@reach/combobox@0.16.5的peer依赖仅支持React 16.8.0或17.x版本，存在版本冲突。
先后尝试使用--legacy-peer-deps参数忽略peer依赖校验、--force参数强制安装依赖两种方案，其中强制安装直接导致项目代码运行异常，目前部署工作完全受阻。

项目package.json配置 #

{
  "name": "find-furry-friends",
  "version": "0.1.0",
  "engines": {
    "node": "16.x"
  },
  "private": true,
  "dependencies": {
    "@hookform/resolvers": "^2.9.4",
    "@reach/combobox": "^0.16.5",
    "@react-google-maps/api": "^2.12.0",
    "@testing-library/jest-dom": "^5.16.4",
    "@testing-library/react": "^13.3.0",
    "@testing-library/user-event": "^13.5.0",
    "bcrypt": "^5.0.1",
    "bootstrap": "^5.1.3",
    "dotenv": "^16.0.1",
    "express": "^4.18.1",
    "jsonwebtoken": "^8.5.1",
    "moment": "^2.29.4",
    "mongoose": "^6.4.0",
    "morgan": "^1.10.0",
    "petfinder-client": "^1.0.2",
    "react": "^18.2.0",
    "react-avatar": "^5.0.1",
    "react-dom": "^18.0.2",
    "react-file-base64": "^1.0.3",
    "react-router-dom": "^6.3.0",
    "react-scripts": "^5.0.1",
    "react-tilty": "^2.0.3",
    "serve-favicon": "^2.5.0",
    "use-places-autocomplete": "^4.0.0",
    "web-vitals": "^2.1.4",
    "yup": "^0.32.11"
  },
  "scripts": {
    "start": "react-scripts start",
    "build": "react-scripts build",
    "test": "react-scripts test",
    "eject": "react-scripts eject"
  },
  "eslintConfig": {
    "extends": [
      "react-app",
      "react-app/jest"
    ]
  },
  "browserslist": {
    "production": [
      ">0.2%",
      "not dead",
      "not op_mini all"
    ],
    "development": [
      "last 1 chrome version",
      "last 1 firefox version",
      "last 1 safari version"
    ]
  },
  "proxy": "http://localhost:3001"
}

可行解决方案 #

• 优先方案：升级@reach/combobox到兼容React 18的版本。0.18.0及以上版本的@reach/combobox已正式支持React 18，本地执行npm install @reach/combobox@latest更新依赖版本即可，更新后不需要加任何强制安装参数，Heroku部署时可正常通过依赖校验，不会出现运行时兼容问题。
• 临时方案：如果暂时不想升级@reach/combobox版本，不要本地执行带参数的安装命令（Heroku部署时不会读取本地命令参数），直接在package.json根节点添加如下配置，让Heroku安装依赖时自动应用--legacy-peer-deps规则：

"npmConfig": {
  "legacy-peer-deps": true
}

该方案比--force安全，不会强制覆盖已有依赖版本，基本不会触发运行时错误。

• 额外配置提醒：当前package.json中的start脚本是开发环境启动命令，Heroku生产环境部署需要在构建完成后用静态服务托管build目录，否则就算依赖安装通过，启动阶段也会超时失败，建议调整start脚本为生产启动命令，或新增Procfile指定生产环境启动逻辑。

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