如何在Heroku上配置GatsbyJS纯客户端路由 解决直接访问URL404问题

根因定位 #

生产环境直访客户端路由返回404，由三类配置错位共同导致：

• Heroku静态服务的路由重定向目标路径写法错误，深层路由资源定位失败
• 通配路由匹配规则未覆盖全量客户端路由嵌套层级
• 构建流程与静态文件路径映射存在偏差

具体修改步骤 #

1. 修正 static.json 配置 #

你原有配置存在两处关键硬伤：

• 路由重定向目标未加前导斜杠：Heroku静态服务会把无斜杠开头的路径解析为相对当前请求地址的相对路径，例如访问/user/123/edit时，服务端会去寻找不存在的/user/123/user/index.html，直接触发404
• 通配规则的匹配范围没有覆盖深层路由，即使路径写对，嵌套层级超过一层的请求也无法正确转发
  修正后的完整配置参考：

{
  "root": "public/",
  "clean_urls": true,
  "routes": {
    "/user/**": "/user/index.html"
  },
  "https_only": true,
  "error_page": "404.html"
}

注意：routes 字段中的目标路径必须以 / 开头，代表从root指定的public/目录开始查找文件，这是最容易踩的配置坑 #

2. 核对构建产物的实际路径 #

本地执行gatsby build完成构建后，检查public目录下的文件结构：

• 确认存在public/user/index.html，也就是src/pages/user.js对应的构建产出文件
• 排查是否存在与客户端路由冲突的静态文件（比如手动生成的public/user/new.html、public/user/profile/123.html等）：这类文件会触发静态资源的优先匹配规则，绕开自定义的路由重定向逻辑

3. 校准Heroku构建流程 #

在项目根目录的package.json中，确保构建脚本配置正确：

{
  "scripts": {
    "build": "gatsby build",
    "start": "gatsby develop"
  }
}

避免nodejs buildpack跳过Gatsby构建步骤，导致public目录没有生成最新的静态文件，直接触发404。 #

部署验证排查 #

上线后按以下步骤排查残留问题：

• 访问直链时在URL后追加随机查询参数，排除边缘缓存对旧404响应的缓存影响
• 查看Heroku运行日志，确认/user/*前缀的请求，是否被静态服务正确转发到/user/index.html
• 核对gatsby-plugin-create-client-paths的prefix配置，确保和实际路由前缀完全一致，避免路径匹配偏差

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