如何使用GitHub Workflow部署React/Gatsby项目到GitHub Pages并解决图片异常

1. 修正执行命令不匹配问题 #

你本地手动部署执行的是npm run deploy，但当前Workflow中执行的是npm run build，两者逻辑不一致是最常见的故障原因。通常Gatsby项目的deploy命令会包含路径前缀处理、资源优化等专属逻辑，直接替换Workflow中的构建命令即可：
将原有配置中的

- run: npm run build

替换为

- run: npm run deploy

2. 补全代码拉取配置 #

你当前使用的actions/checkout@v2默认仅拉取最近1次提交的浅拷贝，如果你的图片资源存在历史依赖或通过Git LFS存储，会导致CI环境下资源拉取不全，引发图片缺失。修改checkout步骤配置如下：

- uses: actions/checkout@v4
  with:
    fetch-depth: 0 # 拉取全量提交历史
    lfs: true # 未使用Git LFS存储图片可删除该行

3. 校验Gatsby路径前缀配置 #

如果你的GitHub Pages部署在用户名.github.io/仓库名的子路径下，需要在gatsby-config.js中正确配置pathPrefix为你的仓库名，同时构建命令需要添加--prefix-paths参数，示例配置如下：

// package.json scripts字段示例
"deploy": "gatsby build --prefix-paths && gh-pages -d public"

未添加该参数时，CI构建出的资源路径会指向根域名，子路径下的图片会返回404错误。

4. 统一版本避免兼容性问题 #

你当前使用的Action版本、Node版本均较老，和新的Gatsby依赖可能存在兼容性问题，建议将所有Action升级到最新稳定版，同时将CI的Node版本调整为你本地开发使用的版本，保证构建产物一致。

修改后的完整Workflow配置参考：

name: GitHub Pages

on:
  push:
    branches:
      - main
  pull_request:

jobs:
  deploy:
    runs-on: ubuntu-latest
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '18' # 替换为你本地使用的Node版本
          cache: 'npm'

      - run: npm ci
      - run: npm run format
      - run: npm run deploy

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v4
        if: ${{ github.ref == 'refs/heads/main' }}
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public

内容的提问来源于stack exchange，提问作者J.erome