为 HagiCode 添加 GitHub Pages 自动部署支持本项目早期代号为 PCode现已正式更名为 HagiCode。本文记录了如何为项目引入自动化静态站点部署能力让内容发布像喝水一样简单。背景/引言在 HagiCode 的开发过程中我们遇到了一个很现实的问题随着文档和提案越来越多如何高效地管理和展示这些内容成了当务之急。我们决定引入 GitHub Pages 来托管我们的静态站点但是手动构建和部署实在是太麻烦了——每次改动都要本地构建、打包然后手动推送到 gh-pages 分支。这不仅效率低下还容易出错。为了解决这个问题主要是为了偷懒我们需要一套自动化的部署流程。本文将详细记录如何为 HagiCode 项目添加 GitHub Actions 自动部署支持让我们只需专注于内容创作剩下的交给自动化流程。关于 HagiCode嘿介绍一下我们正在做的东西我们正在开发 HagiCode——一款 AI 驱动的代码智能助手让开发体验变得更智能、更便捷、更有趣。智能——AI 全程辅助从想法到代码让编码效率提升数倍。便捷——多线程并发操作充分利用资源开发流程顺畅无阻。有趣——游戏化机制和成就系统让编码不再枯燥充满成就感。项目正在快速迭代中如果你对技术写作、知识管理或者 AI 辅助开发感兴趣欢迎来 GitHub 看看目标分析在动手之前我们得先明确这次任务到底要干啥。毕竟磨刀不误砍柴工嘛。核心需求自动化构建当代码推送到 main 分支时自动触发构建流程。自动部署构建成功后自动将生成的静态文件部署到 GitHub Pages。环境一致性确保 CI 环境和本地构建环境一致避免本地能跑线上报错的尴尬。技术选型考虑到 HagiCode 是基于 Docusaurus 构建的一种非常流行的 React 静态站点生成器我们可以利用 GitHub Actions 来实现这一目标。配置 GitHub Actions 工作流GitHub Actions 是 GitHub 提供的 CI/CD 服务。通过在代码仓库中定义 YAML 格式的工作流文件我们可以定制各种自动化任务。创建工作流文件我们需要在项目根目录下的 .github/workflows 文件夹中创建一个新的配置文件比如叫 deploy.yml。如果文件夹不存在记得先手动创建一下。这个配置文件的核心逻辑如下触发条件监听 main 分支的 push 事件。运行环境最新版的 Ubuntu。构建步骤检出代码安装 Node.js安装依赖 (npm install)构建静态文件 (npm run build)部署步骤使用官方提供的 action-gh-pages 将构建产物推送到 gh-pages 分支。关键配置代码以下是我们最终采用的配置模板name: Deploy to GitHub Pages# 触发条件当推送到 main 分支时on:push:branches:- main# 可以根据需要添加路径过滤比如只有文档变动才构建# paths:# - docs/**# - package.json# 设置权限这对于部署到 GitHub Pages 很重要permissions:contents: readpages: writeid-token: write# 并发控制取消同一分支的旧构建concurrency:group: pagescancel-in-progress: falsejobs:build:runs-on: ubuntu-lateststeps:- name: Checkoutuses: actions/checkoutv4# 注意必须设置 fetch-depth: 0否则可能导致构建版本号不准确with:fetch-depth: 0- name: Setup Nodeuses: actions/setup-nodev4with:node-version: 20 # 建议与本地开发环境保持一致cache: npm # 启用缓存可以加速构建过程- name: Install dependenciesrun: npm ci# 使用 npm ci 而不是 npm install因为它更快、更严格适合 CI 环境- name: Build websiterun: npm run buildenv:# 如果你的站点构建需要环境变量在这里配置# NODE_ENV: production# PUBLIC_URL: /your-repo-name- name: Upload artifactuses: actions/upload-pages-artifactv3with:path: ./build # Docusaurus 默认输出目录deploy:environment:name: github-pagesurl: ${{ steps.deployment.outputs.page_url }}runs-on: ubuntu-latestneeds: buildsteps:- name: Deploy to GitHub Pagesid: deploymentuses: actions/deploy-pagesv4实施过程中的坑点在实际操作中我们遇到了一些问题这里分享出来希望大家能避开或者提前准备好解决方案。1. GitHub Token 权限问题最开始配置的时候部署总是报错 403 (Forbidden)。查了好久才发现是因为 GitHub 默认的 GITHUB_TOKEN 并没有写入 Pages 的权限。解决方案在仓库的 Settings - Actions - General - Workflow permissions 中务必选择 Read and write permissions。2. 构建目录路径错误Docusaurus 默认把构建好的静态文件放在 build 目录。但是有些项目比如 Create React App 默认是 buildVite 默认是 dist可能配置不一样。如果在 Actions 中报错找不到文件记得去 docusaurus.config.js 里检查一下输出路径配置。3. 子路径问题如果你的仓库不是用户主页即不是 username.github.io而是项目主页比如 username.github.io/project-name你需要配置 baseUrl。在 docusaurus.config.js 中module.exports {// ...url: https://HagiCode-org.github.io, // 你的 GitHub URLbaseUrl: /site/, // 如果你的仓库叫 site这里就填 /site/// ...};这一点很容易被忽略配置不对会导致页面打开全是白屏因为资源路径加载不到。验证成果配置完所有东西并推送代码后我们就可以去 GitHub 仓库的 Actions 标签页看戏了。你会看到黄色的圆圈工作流正在运行变绿就代表成功啦如果变红了点击进去查看日志通常都能排查出问题大部分时候是拼写错误或者路径配置不对。构建成功后访问 https://你的用户名.github.io/仓库名/ 就能看到崭新的站点了。总结通过引入 GitHub Actions我们成功实现了 HagiCode 文档站的自动化部署。这不仅节省了手动操作的时间更重要的是保证了发布流程的标准化。现在不管是哪位小伙伴更新了文档只要合并到 main 分支几分钟后就能在线上看到最新的内容。核心收益效率提升从手动打包、手动上传变成代码即发布。降低错误消除了人为操作失误的可能性。体验优化让开发者更专注于内容质量而不是被繁琐的部署流程困扰。涯戏咎瞪