Heroku部署React/Vite项目报错R10 无法绑定$PORT端口问题

问题核心原因 #

Heroku平台对Web进程有强制启动规则：进程必须在启动后60秒内绑定到平台动态分配的$PORT端口，且必须监听0.0.0.0地址，否则会触发R10 Boot timeout错误，强制杀死进程。
当前配置存在两个核心问题：

1. 启动脚本直接运行vite启动开发服务器，默认监听5173端口、仅绑定localhost地址，既没有读取Heroku分配的$PORT，也没有开放外部访问权限
2. 生产环境直接运行Vite开发服务器不符合部署规范，存在性能差、安全风险高、资源占用大的问题
   之前将NPM_CONFIG_PRODUCTION、YARN_PRODUCTION设为false只是解决了生产模式下npm不安装devDependencies导致vite命令找不到的问题，没有解决端口绑定和启动逻辑的核心错误。

分步修复操作 #

1. 调整依赖和启动脚本 #

首先安装生产环境用的静态文件服务包serve，用于托管Vite构建后的静态产物：

npm install serve --save

修改package.json中的scripts配置，替换原有的start脚本，增加Heroku专属构建脚本：

"scripts": {
  "dev": "vite",
  "build": "tsc && vite build",
  "start": "serve -s dist -l $PORT",
  "heroku-postbuild": "npm run build",
  "postcss-run": "postcss ./public/index.css --dir public --watch"
}

脚本说明：

• heroku-postbuild是Heroku部署时自动触发的构建钩子，会在依赖安装完成后自动执行Vite构建，生成dist静态产物目录
• start脚本用serve托管dist目录：-s参数启用单页应用模式，适配react-router的前端路由刷新逻辑；-l $PORT指定服务监听Heroku动态分配的端口

2. （可选）调整Vite配置适配部署环境 #

如果需要在本地或其他环境用vite dev模式启动时也兼容端口规则，可以修改项目根目录的vite.config.ts，增加server配置：

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  server: {
    host: '0.0.0.0',
    port: process.env.PORT ? Number(process.env.PORT) : 5173
  }
})

3. 还原Heroku平台配置 #

将之前修改的NPM_CONFIG_PRODUCTION、YARN_PRODUCTION两个配置项改回默认值true。
Heroku在检测到heroku-postbuild脚本时，会自动在构建阶段安装全部依赖（包括devDependencies），构建完成后自动裁剪掉开发依赖，不需要手动关闭生产依赖安装规则，还能有效降低部署包体积、加快启动速度。

排查校验清单 #

• 本地先执行npm run build，确认dist目录正常生成，没有TS编译错误、Vite构建错误
• 所有启动服务的命令禁止硬编码固定端口，必须读取$PORT环境变量
• 服务必须监听0.0.0.0地址，不能仅绑定127.0.0.1/localhost，否则Heroku路由层无法转发请求
• 禁止在生产环境运行vite/vite dev这类开发服务器命令，必须使用静态服务托管构建后的产物

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