实战指南：基于GitHub Actions的Docusaurus站点自动化部署

本项目早期代号为PCode，现已正式更名为HagiCode。本文记录了如何为项目引入自动化静态站点部署能力，让内容发布像喝水一样简单。

在技术项目快速迭代的过程中，高效的文档管理至关重要。手动构建和部署静态站点不仅耗时，还容易出错。本文将分享我们为HagiCode项目配置自动化部署的完整过程，如果你也在寻找解放双手的方案，不妨继续往下看。更多类似的运维自动化实践，也可以在云栈社区找到相关讨论。

背景与目标

在HagiCode的开发过程中，我们面临一个现实问题：文档和提案越来越多，如何高效地管理和展示这些内容？我们决定使用GitHub Pages托管静态站点，但每次手动构建并推送到 gh-pages 分支的流程既低效又易错。

为了彻底解决这个问题（或者说，为了“偷懒”），我们决定引入一套自动化部署流程。目标是：当代码推送到 main 分支时，自动完成构建，并将生成的站点部署到GitHub Pages。

核心需求

1. 自动化构建：代码推送至 main 分支即触发构建。
2. 自动部署：构建成功后，自动将静态文件部署至GitHub Pages。
3. 环境一致性：确保CI/CD环境与本地开发环境一致，避免“本地能跑，线上报错”的窘境。

技术选型

HagiCode的文档站基于Docusaurus构建，这是一款流行的React静态站点生成器。实现自动化的最佳拍档，自然选择了GitHub自家的CI/CD服务——GitHub Actions。

配置GitHub Actions工作流

GitHub Actions允许你通过仓库内的YAML文件定义自动化工作流。下面是我们一步步搭建部署管线的过程。

创建工作流文件

首先，在项目根目录创建 .github/workflows/ 文件夹（如果不存在的话），然后在该文件夹内新建一个YAML配置文件，例如 deploy.yml。

这个文件的核心逻辑如下：

1. 触发条件：监听 main 分支的 push 事件。
2. 运行环境：使用最新版的Ubuntu系统。
3. 构建步骤：
   • 检出代码
   • 安装Node.js
   • 安装项目依赖 (npm install)
   • 构建静态文件 (npm run build)
4. 部署步骤：使用官方Actions将构建产物部署到GitHub Pages。

核心配置代码

以下是我们最终采用的工作流配置模板，包含了详细的注释说明：

name: Deploy to GitHub Pages

# 触发条件：当推送到 main 分支时
on:
  push:
    branches:
      - main
  # 可以根据需要添加路径过滤，比如只有文档变动才构建
  # paths:
  #   - 'docs/**'
  #   - 'package.json'

# 设置权限，这对于部署到 GitHub Pages 很重要
permissions:
  contents: read
  pages: write
  id-token: write

# 并发控制：取消同一分支的旧构建
concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        # 注意：必须设置 fetch-depth: 0，否则可能导致构建版本号不准确
        with:
          fetch-depth: 0

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 20 # 建议与本地开发环境保持一致
          cache: 'npm' # 启用缓存可以加速构建过程

      - name: Install dependencies
        run: npm ci
        # 使用 npm ci 而不是 npm install，因为它更快、更严格，适合 CI 环境

      - name: Build website
        run: npm run build
        env:
          # 如果你的站点构建需要环境变量，在这里配置
          # NODE_ENV: production
          # PUBLIC_URL: /your-repo-name

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./build # Docusaurus 默认输出目录

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

实施过程中的常见问题与解决方案

配置过程并非一帆风顺，我们遇到了一些典型的“坑”。这里列出来，希望能帮你提前避雷。

1. GitHub Token 权限问题

最初部署时，频繁遇到403 (Forbidden)错误。根本原因是默认的 GITHUB_TOKEN 没有写入Pages的权限。

解决方案：进入仓库的 Settings -> Actions -> General -> Workflow permissions，务必选择 “Read and write permissions”。

2. 构建输出目录路径错误

Docusaurus默认的构建输出目录是 build。但不同框架的默认输出目录可能不同（例如Create React App是 build，Vite是 dist）。如果在Actions日志中看到“文件未找到”的错误，请检查 docusaurus.config.js 中的输出路径配置。

3. 仓库子路径配置问题

如果你的站点不是用户主页（username.github.io），而是项目主页（username.github.io/repo-name），则必须在Docusaurus配置中正确设置 baseUrl。

在 docusaurus.config.js 中：

module.exports = {
  // ...
  url: 'https://HagiCode-org.github.io', // 你的 GitHub URL
  baseUrl: '/site/', // 如果你的仓库叫 site，这里就填 /site/
  // ...
};

这一点至关重要，配置错误会导致页面白屏，因为所有静态资源的路径都会加载失败。

如何验证部署成果

完成配置并将代码推送到 main 分支后，就可以前往GitHub仓库的 Actions 标签页查看流水线运行状态了。

你会看到一个黄色的圆圈（表示工作流正在运行），变成绿色即代表成功！如果变成红色，点击进入查看详细日志，通常能快速定位问题（大多是拼写错误或路径配置问题）。

构建部署成功后，访问 https://<你的用户名>.github.io/<仓库名>/ 即可看到焕然一新的线上站点。

总结与收益

通过引入GitHub Actions，我们成功实现了HagiCode文档站的自动化部署。这不仅节约了时间，更关键的是建立了标准化的发布流程。现在，任何团队成员更新文档后，只需合并到 main 分支，几分钟后线上就能同步更新。

核心收益：

• 效率飞跃：从繁琐的“手动打包、手动上传”转变为优雅的“代码即发布”。
• 错误率降低：消除了人为操作失误的风险。
• 体验优化：开发者可以更专注于内容创作，而非被部署流程困扰。

虽然初期配置CI/CD会遇到一些权限、路径上的小麻烦，但这是一次投入、长期受益的工作。对于任何静态站点项目，尤其是像我们这样活跃在GitHub上的开源项目，强烈建议搭建类似的自动化流程。