Gatsby部署到Github Pages缺失文件、路由404，本地运行无异常

你遇到的两类异常核心诱因是：Gatsby 站点部署在 Github Pages 的子路径下，而本地运行时站点服务在根路径，路径匹配逻辑不一致触发报错，具体拆分如下：

• 静态资源404：Gatsby 默认生成的静态资源路径基于站点根路径，你的 Github Pages 站点实际服务路径是带仓库名的子路径，根路径下不存在对应资源，所以触发加载失败。该问题出现的前提是你未在 Gatsby 配置中声明pathPrefix，或是构建时未添加--prefix-paths参数，配置未生效。
• /code路由404：
  1. 未配置pathPrefix时，Gatsby 生成的 code 页面对应的实际访问路径为/giorgio-martini/code/，如果菜单栏跳转逻辑直接写了绝对路径/code，会跳转到根路径下的不存在地址。
  2. 即便配置了pathPrefix，如果未使用 Gatsby 内置的Link组件处理路由跳转，而是用原生a标签或手动写死绝对路径，也会跳过pathPrefix的自动补全逻辑，导致路径错误。
  3. 额外说明：Github Pages 本身不支持单页应用的客户端路由 fallback，即便是路径配置正确，直接刷新二级路由也会触发404，需要额外添加404.html适配逻辑。

• 第一步：在项目根目录的gatsby-config.js中添加pathPrefix配置：

module.exports = {
  pathPrefix: "/giorgio-martini",
  // 其余原有配置保持不变
}

• 第二步：修改package.json中的构建命令，添加--prefix-paths参数让配置生效：

{
  "scripts": {
    "build": "gatsby build --prefix-paths"
  }
}

• 第三步：检查所有路由跳转逻辑，统一使用 Gatsby 提供的Link组件实现跳转，不要手动写死绝对路径：

import { Link } from "gatsby"
// 正确写法，自动补全pathPrefix
<Link to="/code">Code</Link>

• 第四步：重新构建部署即可解决现有问题。

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