Heroku免费计划Node.js应用休眠后请求唤醒崩溃如何解决

AI 小北

2026-8-28

问题根因

该故障与Heroku免费计划的休眠唤醒逻辑无直接关联，核心诱因是GitHub集成部署场景下webpack构建配置存在缺陷：webpack生成的生产环境构建产物未被打包进Heroku部署用的只读运行镜像（slug）。
Heroku Node.js环境的标准构建、运行逻辑如下：构建阶段会安装所有依赖（包括devDependencies下的webpack等构建工具），执行完构建脚本后会自动删除devDependencies以压缩镜像体积；后续dyno休眠唤醒、异常重启时，只会直接执行预设的启动命令，不会重新触发构建流程，且dyno运行时的文件系统是临时存储，dyno停止后所有运行时生成的文件会被完全清空。
你首次部署后应用可正常运行，基本是首次部署时通过手动执行heroku bash构建、或启动脚本夹带构建命令偶然执行成功，生成的构建产物存放在临时文件系统中；休眠触发dyno关停后临时文件被清空，唤醒时要么找不到构建后的入口文件，要么因devDependencies已被移除无法重新执行构建，直接抛出H10 App crashed错误。手动执行heroku restart可临时恢复，本质是重启过程偶发触发了临时构建，不属于长效解决方案。

修复配置步骤

按以下顺序调整配置，即可实现休眠后正常自动唤醒：

修正package.json脚本配置
打开项目根目录的package.json，将构建逻辑和启动逻辑完全拆分，禁止在启动脚本中包含webpack等构建命令，避免运行时因缺失构建依赖报错：
```
{
  "scripts": {
    "build": "webpack --mode production",
    "start": "node dist/index.js", // 路径替换为你项目webpack实际输出的入口文件路径
    "heroku-postbuild": "npm run build"
  }
}
```
其中heroku-postbuild是Heroku专属构建钩子，会强制在镜像构建阶段执行webpack打包，确保构建产物被写入只读slug，不会随dyno重启丢失。
校验忽略文件规则
打开项目根目录的.gitignore文件，确认没有将webpack.config.js、.babelrc等构建必需的配置文件加入忽略列表；webpack输出目录（通常为dist//build/）不需要提交到GitHub仓库，构建阶段会自动生成。
配置Procfile明确启动命令
在项目根目录新建无后缀名的Procfile文件，写入明确的web服务启动命令，避免Heroku调用默认启动命令出现异常：
```
web: npm start
```
修正构建阶段环境变量（可选排查项）
如果之前手动修改过Heroku环境变量，执行以下命令确保构建阶段可正常安装开发依赖完成打包：
```
heroku config:set NPM_CONFIG_PRODUCTION=false
heroku config:set NODE_ENV=production
```
该配置仅在构建阶段生效，构建完成后buildpack仍会自动移除devDependencies，不会增加运行镜像体积。
验证唤醒逻辑
将上述配置提交到GitHub对应部署分支，触发自动部署、应用首次启动成功后，不需要等30分钟自然休眠，可执行以下命令模拟休眠唤醒流程验证：
```
heroku ps:scale web=0
# 等待10秒
heroku ps:scale web=1
```
执行后访问应用如果可正常加载，即表示唤醒逻辑修复完成。

额外避坑项

应用监听端口必须使用Heroku动态分配的process.env.PORT变量，禁止硬编码端口，否则首次启动和唤醒都会触发崩溃。
生产环境webpack配置需关闭热更新、devServer等开发模式插件，避免运行时加载不存在的开发依赖报错。
不要将业务需要持久化存储的文件放在dyno本地文件系统，这类文件随dyno重启丢失也会导致启动失败，需对接独立的对象存储服务。

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