首次部署React应用至Heroku时git push失败求助

问题背景 #

首次尝试在Heroku上部署React应用，按教程操作后执行git push heroku main时推送被拒绝，两次尝试均失败，完整执行日志如下：

me@My-MacBook testapp % git push heroku main
Enumerating objects: 22, done.
Counting objects: 100% (22/22), done.
Delta compression using up to 8 threads
Compressing objects: 100% (22/22), done.
Writing objects: 100% (22/22), 307.67 KiB | 8.10 MiB/s, done.
Total 22 (delta 0), reused 0 (delta 0), pack-reused 0
remote: 正在压缩源文件... 完成。
remote: 正在构建源文件：
remote: 
remote: -----> 在Heroku-22栈上构建
remote: -----> 使用构建包：mars/create-react-app
remote: -----> 检测到React.js（create-react-app）多应用
remote: 
remote: =====! create-react-app-buildpack已停止维护（生命周期结束）🌅
remote:        此次构建可能成功，但该构建包已不再维护。
remote:        在Heroku-22及更高版本的栈上，构建可能完全失败。
remote: 
remote:        请考虑迁移至https://nextjs.org或https://remix.run开发React应用，这些应用可通过Heroku的Node.js构建包https://github.com/heroku/heroku-buildpack-nodejs部署，或者您也可以使用Node.js和Nginx构建包自行实现create-react-app的部署。
remote: 
remote: =====> 正在下载构建包：https://github.com/heroku/heroku-buildpack-multi.git
remote: =====> 检测到框架：Multipack
remote: =====> 正在下载构建包：https://github.com/heroku/heroku-buildpack-nodejs.git
remote: =====> 检测到框架：Node.js
remote:        
remote: -----> 创建运行时环境
remote:        
remote:        NPM_CONFIG_LOGLEVEL=error
remote:        NODE_VERBOSE=false
remote:        NODE_ENV=production
remote:        NODE_MODULES_CACHE=true
remote:        
remote: -----> 安装二进制文件
remote:        engines.node（package.json）：未指定
remote:        engines.npm（package.json）：未指定（使用默认值）
remote:        
remote: 正在解析node版本18.x...
remote: 正在下载并安装node 18.13.0...
remote: 使用默认npm版本：8.19.3
remote:        
remote: -----> 安装依赖
remote:        正在安装node模块
remote:        
remote: 已添加1470个包，在19秒内完成1471个包的审计
remote:        
remote: 231个包正在寻求资助
remote:          运行`npm fund`查看详情
remote:        
remote: 6个高严重性漏洞
remote:        
remote: 要解决所有问题（包括破坏性变更），请运行：
remote:          npm audit fix --force
remote:        
remote: 运行`npm audit`查看详情。
remote:        
remote: -----> 构建
remote:        正在运行构建
remote:        
remote:        > testapp@0.1.0 build
remote:        > react-scripts build
remote:        
remote: 正在创建优化的生产构建...
remote: 编译成功。
remote:        
remote: 压缩后的文件大小：
remote:        
remote:          46.6 kB  build/static/js/main.c9d4c383.js
remote:          1.78 kB  build/static/js/787.49a3df42.chunk.js
remote:          541 B    build/static/css/main.073c9b0a.css
remote:        
remote: 项目构建假设托管在/路径下。
remote: 您可以通过package.json中的homepage字段控制此设置。
remote:        
remote: build文件夹已准备好部署。
remote: 您可以使用静态服务器来托管：
remote:        
remote:          npm install -g serve
remote:          serve -s build
remote:        
remote: 了解更多部署信息请访问：
remote:        
remote:          https://cra.link/deployment
remote:        
remote:        
remote: -----> 缓存构建
remote:        - npm缓存
remote:        
remote: -----> 移除开发依赖
remote:        
remote: 已更新，在4秒内完成1471个包的审计
remote:        
remote: 231个包正在寻求资助
remote:          运行`npm fund`查看详情
remote:        
remote: 6个高严重性漏洞
remote:        
remote: 要解决所有问题（包括破坏性变更），请运行：
remote:          npm audit fix --force
remote:        
remote: 运行`npm audit`查看详情。
remote:        
remote: -----> 构建成功！
remote: =====> 正在下载构建包：https://github.com/mars/create-react-app-inner-buildpack.git#v9.0.0
remote: =====> 检测到框架：React.js（create-react-app）
remote:        正在写入`static.json`以支持create-react-app
remote:        启用运行时环境变量
remote: =====> 正在下载构建包：https://github.com/heroku/heroku-buildpack-static.git#21c1f5175186b70cf247384fd0bf922504b419be
remote: =====> 检测到框架：Static HTML
remote: 栈heroku-22不被支持！
remote:  !     推送被拒绝，React.js（create-react-app）多应用编译失败。
remote: 
remote:  !     推送失败
remote:  !
remote:  ! ## 警告 - 相同版本的代码已构建过：f609d0c54516882f24faf2a1b4fcad975cc76b04
remote:  !
remote:  ! 我们检测到您已触发过版本为f609d0c54516882f24faf2a1b4fcad975cc76b04的源代码构建至少两次。
remote:  ! 常见原因之一是尝试从不同分支部署代码。
remote:  !
remote:  ! 如果您在分支上开发并通过git部署，必须运行：
remote:  !
remote:  !     git push heroku <branchname>:main
remote:  !
remote:  ! 有关此行为的详细信息请查看文章：
remote:  !   https://devcenter.heroku.com/articles/duplicate-build-version
remote: 
remote: 正在验证部署...
remote: 
remote: !   推送被拒绝至testapp。
remote: 
To https://git.heroku.com/testapp.git
 ! [remote rejected] main -> main (pre-receive hook declined)
error: failed to push some refs to 'https://git.heroku.com/testapp.git'
me@My-MacBook testapp % 

问题原因 #

日志明确提示create-react-app-buildpack已停止维护，且栈heroku-22不被支持——旧的第三方构建包已无法兼容Heroku最新的栈版本，导致构建流程失败。

解决步骤 #

1. 移除旧构建包 #

执行命令清除当前应用使用的过时构建包：

heroku buildpacks:remove mars/create-react-app

2. 设置官方Node.js构建包 #

切换到Heroku官方支持的Node.js构建包：

heroku buildpacks:set heroku/nodejs

3. 添加静态服务配置文件 #

在项目根目录创建static.json文件，用于处理React单页应用的路由跳转：

{
  "root": "build/",
  "clean_urls": false,
  "routes": {
    "/**": "index.html"
  }
}

4. 验证package.json配置 #

确保package.json中包含正确的build脚本（create-react-app默认已生成）：

"scripts": {
  "start": "react-scripts start",
  "build": "react-scripts build",
  "test": "react-scripts test",
  "eject": "react-scripts eject"
}

5. 提交修改并重新推送 #

git add static.json
git commit -m "Add static config for Heroku deployment"
git push heroku main

可选：指定Node.js版本 #

在package.json中添加engines字段，指定兼容的Node.js和npm版本，避免版本兼容问题：

"engines": {
  "node": "18.x",
  "npm": "8.x"
}

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