🐙 GitHub Pages 部署指南
GitHub Pages 是 GitHub 提供的静态站点托管服务。本文记录使用 GitHub Pages 部署 Quartz 站点的方案，以及与 Cloudflare Pages 的对比。
当前状态：本站未使用 GitHub Pages，改用 Cloudflare Pages（见 Cloudflare Pages 部署指南）。本文保留作为备选方案参考。
🎯 方案对比
| 对比项 | GitHub Pages | Cloudflare Pages |
|---|---|---|
| 构建环境 | 需要 GitHub Actions | 自带 CI |
| 全球 CDN | 无 | 默认开启 |
| 自定义域名 | 支持，SSL 自动 | 支持，SSL 自动 |
| 构建限制 | 每周 10 次 | 每月 500 次 |
| 输出目录 | 仓库根或 docs/ | 任意路径 |
| 国内访问 | 慢 | 快 |
🛠️ 1. GitHub Actions 部署流程
如果不使用 Cloudflare Pages，可以用 GitHub Actions 自动构建并部署到 GitHub Pages。
创建 workflow
在仓库根创建 .github/workflows/deploy.yaml：
name: Deploy Quartz site to GitHub Pages
on:
push:
branches: [main]
permissions:
contents: read
pages: write
id-token: write
concurrency:
group: pages
cancel-in-progress: false
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
# 注：fetch-depth: 0 是为完整 git 历史。日期字段现已由 vault 源文件的
# frontmatter 维护（Obsidian Linter 自动写入），构建不再读 git 时间，
# 所以这个选项对构建结果无影响，保留只是无害。
- name: Setup Node
uses: actions/setup-node@v4
with:
node-version: ">=22"
- name: Install dependencies
run: cd .quartz && npm ci
- name: Sync content
run: node .scripts/sync-content.mjs
- name: Build Quartz
run: cd .quartz && npx quartz build -d content
- name: Upload artifact
uses: actions/upload-pages-artifact@v3
with:
path: .quartz/public
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启用 GitHub Pages
- 仓库 → Settings → Pages
- Source 选择 GitHub Actions
- 推送 workflow 文件后自动触发首次构建
⚙️ 2. 关键配置
quartz.config.yaml
configuration:
baseUrl: lihuohuo1988.github.io/NotebookAI # GitHub Pages 子路径GitHub Pages 托管在 https://<用户名>.github.io/<仓库名>/，所以 baseUrl 需要包含仓库名。
CNAME 自定义域名
如果使用自定义域名：
- 在
.quartz/static/目录放一个CNAME文件，内容是域名 - GitHub 自动配置 DNS 验证
⚠️ 3. 已知问题
- 无 CDN：国内访问 GitHub Pages 很慢
- 构建限制：每周 10 次构建，频繁更新容易超限
- 子路径问题：
baseUrl需要包含仓库名，路径解析容易出错 - SSL 证书：自定义域名首次配置需要等待证书签发
📦 4. 发布前置条件
构建命令依赖 vault 根的 .scripts/sync-content.mjs 把内容复制到
.quartz/content/。CI 里少这一步会构建出空站，所以 workflow 里必须：
- run: node .scripts/sync-content.mjs # 在 vault 根执行
- run: cd .quartz && npx quartz build -d content顺序不能颠倒，且 -d content 不能省。详细机制见 Quartz 5 配置指南。
🔗 5. 与 Quartz 的关联
本站使用 Quartz 5 生成静态站点，GitHub Pages 是备选部署方案。相关笔记：
- Quartz 5 配置指南 — Quartz 安装、配置、插件、构建命令详解
- Cloudflare Pages 部署指南 — 本站实际使用的部署方案
- 模板说明 — vault 字段约定与
type词表
关键配置
quartz.config.yaml 中影响部署的配置：
configuration:
baseUrl: lihuohuo1988.github.io/NotebookAI # GitHub Pages 子路径
enableSPA: true # ← 已开启；曾因误判的 404 问题设为false，现已修复
ignorePatterns: [] # ← 刻意留空，发布范围由同步脚本决定
fontOrigin: googleFonts # ← 国内访问建议改 local⚠️ 不要配置「自动补尾斜杠」的重写规则。Quartz v5.0.0 的资源前缀计算对带尾
斜杠的 URL 会少退一级，导致整页资源 404。这与enableSPA无关，详见
Cloudflare Pages 部署指南 末尾说明。