通过GitHub部署Node应用到Heroku时未执行npm build,触发H10 App崩溃错误
Heroku部署失败根因与修复方案
已定位的核心配置问题
- 启动脚本与Heroku运行流程不匹配
Heroku Node应用的标准执行链路为:拉取源码 → 安装生产依赖 → 安装构建所需devDependencies → 执行heroku-postbuild自定义构建逻辑 → 正式启动dyno时默认执行npm start命令。
你观察到Heroku未执行构建、直接运行npm start的核心原因是:当前start脚本指向开发专用的webpack-dev-server,该命令携带的--open参数需要图形界面支持,在Heroku无界面环境中会直接报错;同时错误地将生产服务启动逻辑写入heroku-postbuild——该阶段的进程运行在临时构建环境中,会随构建流程结束被销毁,无法对外提供服务,最终启动阶段跑的还是开发版的服务命令。 - 生产运行依赖缺失
server.js核心逻辑依赖express模块,但package.json的dependencies列表未声明该依赖。Heroku生产环境启动时不会加载devDependencies中的包,执行服务启动命令会直接抛出模块找不到的错误,这是触发H10 503错误的直接诱因。 - 静态资源路径配置错误
当前server.js的页面fallback逻辑指向项目根目录的index.html,但webpack生产构建生成的入口文件实际存储在dist目录下,路径不匹配会导致服务无法正确返回页面内容。 - 无效依赖冗余
devDependencies中混入了install、npm两个全局工具包,既不参与项目构建逻辑,还可能引发依赖安装冲突,拖慢构建速度。
对应修复操作
- 调整package.json脚本配置
从heroku-postbuild中移除错误的服务启动命令,仅保留生产构建逻辑;将start脚本替换为生产环境的服务启动命令,删除开发专用的dev-server启动逻辑:
"scripts": { "dev": "webpack-dev-server", "build": "webpack --mode production", "start": "node server.js", "heroku-postbuild": "npm run build" }
- 补全生产依赖、清理无效包
将express加入生产依赖列表,移除devDependencies中无用的冗余包:
npm install express --save npm uninstall install npm --save-dev
- 修正server.js的路径引用
调整静态资源托管路径与页面fallback逻辑,指向webpack打包后的dist目录:
const express = require('express'); const path = require('path'); const port = process.env.PORT || 8080; const app = express(); // 托管打包后的静态资源 app.use(express.static(path.join(__dirname, 'dist'))); // 所有路由统一返回入口HTML app.get('*', (req, res) => { res.sendFile(path.join(__dirname, 'dist', 'index.html')); }); app.listen(port, () => console.log(`App started on port ${port}`));
- 部署前本地校验
提交修改后的代码触发Heroku重新部署前,可在本地通过heroku local命令模拟生产环境启动流程,提前排查模块缺失、路径错误等问题。
内容的提问来源于stack exchange,提问作者Levon Saiyan
相关产品推荐
相关产品推荐

