部署于Heroku的Go+React SPA刷新或外跳非首页时出现404错误

核心问题根因 #

你碰到的404完全是架构配置打架导致的，和static.json本身的配置正确性无关：

• 你当前启用了Docker构建流程，所有线上请求会直接进入你容器内运行的Gin服务，Heroku端挂载的两个静态类buildpack、编写的static.json配置在这个模式下完全不生效——Docker容器的运行逻辑和Heroku原生buildpack的静态托管逻辑是彻底独立的两套体系，这也是你把static.json在应用根目录、client目录反复移动都没有效果的核心原因
• 你在Gin中配置了托管./web路径下的静态资源，但没有添加SPA应用必备的路由兜底规则，碰到非首页的路径请求时，Gin找不到对应的接口或静态文件，就会直接返回404。

具体修复步骤 #

保留Docker部署模式（最适配你当前Gin+前端的架构） #

• 先移除Heroku上所有多余的静态类buildpack（包括https://buildpack-registry.s3.amazonaws.com/buildpacks/heroku-community/static.tgz、https://github.com/mars/create-react-app-buildpack）——Docker模式下这些buildpack不会参与实际构建流程，保留只会增加不必要的排障成本
• 检查Dockerfile的完整构建流程，确保React打包产物真的被拷贝到容器内的./web路径：
  补全Dockerfile里的多阶段构建配置，先完成client目录下React项目的生产构建，再把构建输出的build目录内容复制到容器内对应Gin读取的./web路径，避免只拷贝Go后端代码就直接启动服务
• 修改Gin的路由配置，补全SPA兜底规则：

  import "strings"
  
  // 原有静态资源托管逻辑
  r.Static("/", "./web")
  
  // 新增兜底规则：所有非API类的未匹配请求，统一返回index.html
  r.NoRoute(func(c *gin.Context) {
      // 注意排除API接口路径，不要把后端正常的404接口也改成返回前端页面
      if !strings.HasPrefix(c.Request.URL.Path, "/api/") {
          c.File("./web/index.html")
      }
  })
  

• 重新部署应用后，非首页的刷新、外部站点跳转的请求就会被Gin的兜底规则正确拦截，不会再触发404。

放弃Docker部署，走Heroku原生构建流程 #

如果不想用Docker打包应用，可以调整架构为Heroku原生构建模式，这时候static.json配置才会真正发挥作用：

• 调整Heroku上的buildpack顺序，只保留两类必要的buildpack：
  第一顺位使用官方Go buildpack，处理Gin后端服务的构建和运行；移除所有重叠的静态托管类buildpack，避免构建路径混乱、静态资源处理权被抢夺
• 调整static.json的存放位置和配置：
  如果选择单独用静态buildpack托管前端，要把React项目打包后的产物路径对应到static.json的root配置项，不要把static.json放在Go项目的根目录；保留现有"/**": "index.html"的路由规则，匹配前端路由的跳转逻辑
• 后端Gin服务只挂载/api前缀的接口路由，所有非API路径的请求全部交给Heroku的静态buildpack处理，两套路由职责分离就不会出现404冲突。

常见踩坑提醒 #

• 不要同时让Gin和Heroku静态buildpack处理前端静态资源，两套规则并行一定会出现路径匹配冲突，最终的404问题会反复排查不到根源
• https_only、HSTS响应头这类配置，如果走Docker模式，需要在Gin的中间件里配置，靠static.json在Docker模式下是没法生效的
• 本地开发测试时，可以在启动Gin服务后直接手动访问几个非首页的路径，验证兜底规则是否生效，不用每次都推送到Heroku上测试。

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