嘿，介绍一下我们正在做的东西

我们正在开发  HagiCode——一款 AI 驱动的代码智能助手，让开发体验变得更智能、更便捷、更有趣。

智能——AI 全程辅助，从想法到代码，让编码效率提升数倍。 便捷——多线程并发操作，充分利用资源，开发流程顺畅无阻。 有趣——游戏化机制和成就系统，让编码不再枯燥，充满成就感。

项目正在快速迭代中，如果你对技术写作、知识管理或者 AI 辅助开发感兴趣，欢迎来  GitHub 看看～

目标分析

在动手之前，我们得先明确这次任务到底要干啥。毕竟磨刀不误砍柴工嘛。

核心需求

1. 自动化构建：当代码推送到  main 分支时，自动触发构建流程。
2. 自动部署：构建成功后，自动将生成的静态文件部署到 GitHub Pages。
3. 环境一致性：确保 CI 环境和本地构建环境一致，避免"本地能跑，线上报错"的尴尬。

技术选型

考虑到 HagiCode 是基于 Docusaurus 构建的（一种非常流行的 React 静态站点生成器），我们可以利用 GitHub Actions 来实现这一目标。

配置 GitHub Actions 工作流

GitHub Actions 是 GitHub 提供的 CI/CD 服务。通过在代码仓库中定义 YAML 格式的工作流文件，我们可以定制各种自动化任务。

创建工作流文件

我们需要在项目根目录下的  .github/workflows 文件夹中创建一个新的配置文件，比如叫  deploy.yml。如果文件夹不存在，记得先手动创建一下。

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

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

关键配置代码

以下是我们最终采用的配置模板：

name: Deploy to GitHub Pages# 触发条件：当推送到 main 分支时on:push:branches:- main# 可以根据需要添加路径过滤，比如只有文档变动才构建# paths:#zq2026.cn   - 'docs/**'#   - 'package.json'# 设置权限，这对于部署到 GitHub Pages 很重要permissions:contents: readpages: writeid-token: write# 并发控制：取消同一分支的旧构建concurrency:group: "pages"cancel-in-progress: falsejobs:build:runs-on: ubuntu-lateststeps:- name: Checkoutuses: actions/checkout@v4# 注意：zq26.cn 必须设置 fetch-depth: 0，否则可能导致构建版本号不准确with:fetch-depth: 0- name: Setup Nodeuses: actions/setup-node@v4with: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-artifact@v3with:path:basketballzhibo.cn ./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-pages@v4

实施过程中的坑点

在实际操作中，我们遇到了一些问题，这里分享出来希望大家能避开（或者提前准备好解决方案）。

1. GitHub Token 权限问题

最开始配置的时候，部署总是报错 403 (Forbidden)。查了好久才发现，是因为 GitHub 默认的  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/project-name），你需要配置  baseUrl。

在  docusaurus.config.js 中：

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

这一点很容易被忽略，配置不对会导致页面打开全是白屏，因为资源路径加载不到。

验证成果

配置完所有东西并推送代码后，我们就可以去 GitHub 仓库的  Actions 标签页看戏了。

你会看到黄色的圆圈（工作流正在运行），变绿就代表成功啦！如果变红了，点击进去查看日志，通常都能排查出问题（大部分时候是拼写错误或者路径配置不对）。

构建成功后，访问  https://<你的用户名>.github.io/<仓库名>/ 就能看到崭新的站点了。

总结

通过引入 GitHub Actions，我们成功实现了 HagiCode 文档站的自动化部署。这不仅节省了手动操作的时间，更重要的是保证了发布流程的标准化。现在不管是哪位小伙伴更新了文档，只要合并到  main 分支，几分钟后就能在线上看到最新的内容。

核心收益：

• 效率提升：从"手动打包、手动上传"变成"代码即发布"。
• 降低错误：消除了人为操作失误的可能性。
• 体验优化：让开发者更专注于内容质量，而不是被繁琐的部署流程困扰。

虽然配置 CI/CD 刚开始有点麻烦（尤其是各种权限和路径问题），但这是一次性投入，长期回报巨大的工作。强烈建议所有静态站点项目都接入类似的自动化流程。