GitHub Actions中gatsby build结果与本地不一致问题求助

问题现象 #

• 本地Windows 11环境执行yarn build构建后，首页正常显示home.md内容；但GitHub Actions的Ubuntu环境构建产物中，index.html显示的是about.md内容
• 构建产物大小差异明显：GitHub Actions生成的压缩包仅6.73MB，本地构建的public文件夹为10.4MB
• 本地执行gatsby build --verbose --log-pages时，日志重复输出超10次

排查与解决步骤 #

1. 修复文件系统大小写敏感性问题 #

Windows系统大小写不敏感，而Ubuntu系统严格区分大小写，这是跨环境构建差异的常见原因：

• 确认仓库中home.md、about.md等文件的命名大小写，和本地完全一致（比如避免本地是Home.md、仓库是home.md的情况）
• 检查gatsby-config.js、页面模板及gatsby-node.js中的路径引用，确保路由、文件路径的大小写和实际文件完全匹配（比如不要出现代码中写/About但实际文件是about.md的情况）

2. 强制清理缓存，保证构建环境纯净 #

Gatsby的缓存机制可能导致跨环境构建结果不一致，需在本地和CI环境都清理缓存：

• 本地执行：

  gatsby clean && yarn build
  

• 修改GitHub Actions workflow文件（如.github/workflows/deploy.yml），在构建步骤前添加缓存清理：

  - name: Build Gatsby site
    run: |
      gatsby clean
      yarn build
  

3. 锁定依赖版本一致性 #

恢复yarn install --frozen-lockfile，同时确保本地与CI环境使用相同的Node.js和Yarn版本：

• 在项目根目录创建.nvmrc文件，指定Node.js版本（如v18.17.0）
• 在GitHub Actions中读取该版本，保证环境一致：

  - name: Setup Node.js
    uses: actions/setup-node@v4
    with:
      node-version-file: '.nvmrc'
      cache: 'yarn'
  

4. 检查页面路由与模板匹配逻辑 #

排查gatsby-node.js中的页面生成逻辑，确认首页路由关联正确：

• 查看createPages函数，确保/路由正确绑定到home.md，没有错误将about.md分配到首页路由
• 检查home.md的frontmatter配置，确认slug字段设置为"/"，且未与about.md的slug冲突

5. 解决日志重复输出问题 #

日志重复通常是插件重复注册或页面重复生成导致：

• 检查gatsby-config.js，避免重复注册同一插件（比如多次添加gatsby-source-filesystem指向同一目录）
• 排查gatsby-node.js的createPages函数，确保遍历文件时没有循环调用或重复生成页面的逻辑

6. 对比构建产物定位差异 #

下载GitHub Actions生成的构建压缩包，和本地public文件夹对比：

• 直接查看index.html的内容，确认是否引用了错误的页面数据
• 对比public/page-data目录下的文件，检查首页对应的page-data是否正确关联home.md的内容

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