Heroku git push推送失败 Node.js应用构建被拒故障排查

从构建日志可以确认，失败发生在heroku-postbuild脚本执行阶段，该阶段会执行前端依赖安装、前端资源打包操作，当前日志因日志级别配置仅返回通用失败提示，未输出具体错误根因，按以下步骤逐一排查即可定位问题：

• 本地复现构建流程
  在本地项目根目录直接执行和Heroku构建完全一致的命令，优先在本地复现错误：

  NPM_CONFIG_PRODUCTION=false npm install --prefix frontend && npm run build --prefix frontend
  

  本地执行如果直接报错，根据终端输出修复即可，常见触发场景包括：前端代码存在语法错误、依赖版本冲突、构建时内存溢出、frontend目录下缺失package.json配置文件。
• 核对目录结构配置
  确认项目根目录与frontend目录的层级关系正确，--prefix frontend参数可以正确定位到前端项目路径；如果是多包仓库结构，确认Heroku识别的项目根目录路径正确，避免将上层目录作为根目录推送导致找不到frontend文件夹。
• 开启全量构建日志输出
  临时修改根目录package.json中的heroku-postbuild脚本，开启 verbose 日志模式，打印完整构建过程输出：
  原脚本配置：

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

  修改为：

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

  提交修改后重新执行推送命令，新的构建日志会输出依赖安装、构建执行的全量信息，可直接定位到具体报错点。
• 校验版本配置一致性
  即使已经在根目录package.json的engines字段指定了Node和npm版本，仍需确认两点：一是指定的版本属于Heroku-20栈支持的版本范围，二是frontend目录下的package.json如果存在engines配置，版本要求需与根目录保持一致，避免依赖安装阶段出现版本不兼容问题。
• 清除构建缓存重试
  如果之前有过成功构建记录，大概率是node_modules缓存损坏导致构建失败，先安装Heroku构建插件清除缓存后再重新推送：

  heroku plugins:install heroku-builds
  heroku builds:cache:purge -a 替换为你的Heroku应用名称
  

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