自动化部署流水线
学习目标
- 理解 GitHub Actions 的基本概念
- 掌握三分支策略的同步机制
- 学会配置 GitHub Pages
前置条件
- 完成 02_配置与本地构建
- 了解 section4 的 Git 操作
1. 三分支策略回顾
main ── 日常编辑笔记
│
▼ sync-main-to-v5.yml
v5 ──── Quartz 构建环境
│
▼ deploy.yml
gh-pages ── 静态文件 → GitHub Pages
为什么用三个分支？
| 方案 | 优点 | 缺点 |
|---|---|---|
| 单分支 | 简单 | 仓库混入构建工具文件，Obsidian 中看到 node_modules/ 等 |
| 三分支 | main 保持纯净，构建和发布分离 | 需要同步机制（用 Actions 解决） |
2. 部署工作流（deploy.yml）
监听 v5 分支推送，自动构建并部署。
name: Build and Deploy to GitHub Pages
on:
push:
branches: [v5]
# ...
jobs:
build-and-deploy:
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
- run: npm ci
- run: npx quartz plugin install
- run: npx quartz build
- uses: peaceiris/actions-gh-pages@v4
with:
publish_dir: ./public
publish_branch: gh-pages使用
peaceiris/actions-gh-pages而非actions/deploy-pages，因为前者不受 GitHub Pages 环境保护规则限制。
为什么不直接用 actions/deploy-pages？
GitHub 官方的 deploy-pages 需要 github-pages 环境，且默认有分支保护规则，导致 v5 分支无法部署。peaceiris/actions-gh-pages 直接将构建产物推送到 gh-pages 分支，绕过环境限制。
3. 同步工作流（sync-main-to-v5.yml）
监听 main 分支推送，自动将内容同步到 v5 分支的 content/ 目录。
name: Sync main → v5 and Deploy
on:
push:
branches: [main]
# ...
jobs:
sync:
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: actions/checkout@v4
with:
ref: v5
path: v5-branch
- name: Sync content
run: |
for dir in section0 section1 ... appendix image; do
rsync -a --delete "$dir/" "v5-branch/content/$dir/"
done
cp markdown格式总结.md v5-branch/content/ 2>/dev/null || true
- name: Commit and push
run: |
cd v5-branch
git add content/
git commit -m "sync: 从 main 同步内容更新"
git push同步范围
| 目录/文件 | 同步？ | 说明 |
|---|---|---|
section0/ ~ section9/ | ✅ | 教程章节 |
appendix/ | ✅ | 附录 |
image/ | ✅ | 图片资源 |
markdown格式总结.md | ✅ | 根目录的笔记 |
README.md | ✅ | 仓库说明 |
Clippings/ | ❌ | 网页剪藏 |
template/ | ❌ | 笔记模板 |
.doc/ | ❌ | 内部文档 |
4. GitHub Pages 设置
Actions 配置好后，还需要在 GitHub 上完成 Pages 设置：
- 打开仓库 → Settings → Pages
- Source 选择 Deploy from a branch
- Branch 选择
gh-pages，目录/ (root) - 点击 Save
如果
gh-pages分支还没有（Actions 第一次运行后才生成），可以先选None保存，等 Actions 跑完再回来设置。
5. 完整发布流程
# 1. 编辑笔记（在 main 分支）
git add .
git commit -m "更新笔记"
git push origin main
# 2. 等待 Actions 自动执行
# sync-main-to-v5.yml → deploy.yml
# 3. 访问网站
# https://用户名.github.io/仓库名/两次推送之间约 2-3 分钟网站更新。
扩展阅读
常见问题
Q: Actions 报错 “Branch not allowed to deploy”？
使用 peaceiris/actions-gh-pages 替代 actions/deploy-pages，或在仓库 Settings → Environments 中删除 github-pages 环境。
Q: 同步工作流没有触发？
确认工作流文件在 main 分支的 .github/workflows/ 目录下，且 .gitignore 没有忽略 .github/workflows/。
Q: 网站访问 404？
- 确认 Actions 已完成（绿色勾号）
- 确认 Pages 设置中选择了
gh-pages分支 - 硬刷新浏览器（Ctrl+F5）
练习任务
- 在 GitHub 仓库中查看 Actions 运行情况
- 尝试推送一次 main 分支，观察两个工作流的执行顺序
- 确认网站能正常访问
验收清单
- 理解三分支策略的工作流程
- 知道两个工作流各自的职责
- 完成了 GitHub Pages 设置
- 成功发布了一次网站更新