Heroku部署Vite构建的React应用访问返回404状态码

常见触发场景 #

• 项目基于React + Vite开发，部署到Heroku时使用官方推荐的静态文件buildpack，部署完成后访问站点直接返回404状态码

按优先级排查修复 #

1. 核对buildpack配置与构建流程
   静态部署Vite项目需要按顺序绑定两个buildpack，顺序错误会直接导致构建不生效：

   • 先绑定Node.js buildpack用于执行Vite构建命令
   • 再绑定静态文件buildpack用于托管构建产物
     本地执行以下命令查看当前应用的buildpack列表：

   heroku buildpacks -a 你的Heroku应用名
   

   如果顺序不对或者缺少对应buildpack，按顺序重新添加即可。
   同时查看Heroku部署日志，确认部署过程中成功执行了npm run build命令，日志中能看到Vite构建产物输出到dist目录的提示，没有构建报错、命令不存在类异常。

2. 核对static.json配置
   静态buildpack依赖项目根目录下的static.json读取托管配置，很多人踩过这个坑：把文件放到src、public等子文件夹里，buildpack根本识别不到配置，直接返回默认404。注意这个文件必须放在仓库根目录，且必须提交到Git仓库才会生效。
   单页应用最小可用配置如下，重点要配置路由兜底规则，否则所有前端路由（包括刷新页面时的路径）都会被服务端判定为不存在返回404：

   {
     "root": "dist",
     "clean_urls": true,
     "routes": {
       "/**": "index.html"
     }
   }
   

   配置中的root字段必须和Vite构建输出目录一致，Vite默认输出目录是dist，如果你在vite.config.ts里自定义过build.outDir，这里要同步修改。

3. 核对Vite配置项
   打开vite.config.ts检查两个配置：

   • base字段：如果是部署到站点根域名，保持默认值/即可，不要随意配置子路径，否则会导致静态资源路径全部匹配不上返回404
   • build.outDir字段：如果修改过这个值，要和static.json里的root字段保持一致

4. 核对package.json脚本配置
   确认package.json的scripts字段中存在build命令，且命令内容为vite build，没有拼写错误。不需要把dist目录提交到Git仓库，buildpack会在部署时自动执行构建命令生成最新产物。

验证方法 #

所有配置修改完成后，将变更提交到Git，推送到Heroku远程分支触发重新部署，部署完成后先访问站点根路径确认页面正常加载，再测试子路由跳转、页面刷新操作，确认不会再返回404错误。

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