将 Harness 静态站点托管到 Cloudflare Pages（Git + deploy 分支）

GitHub Actions 构建与 deploy 分支发布，以及 Cloudflare 控制台配置步骤

Cloudflare
GitHub Actions
Quarto
部署
Author

Harness 技术文档

Published

May 11, 2026

1. 总体架构

本仓库采用 「源码在 main，静态产物在 deploy」 的双分支模型：

分支 内容 作用
main Quarto 源码（.qmd、_quarto.yml、资源目录等） 日常开发与版本控制
deploy 仅由 CI 写入：与本地 quarto render 生成的 _site/ 根目录内容一致（HTML、CSS、JS 等） Cloudflare Pages 从 Git 拉取并直接作为静态站点发布

工作流文件：.github/workflows/deploy-cloudflare-pages.yml。

  • 触发条件：向 main 分支 push（任意变更），以及 手动 workflow_dispatch。
  • 步骤：在 Ubuntu 上安装 Quarto → quarto render → 使用 peaceiris/actions-gh-pages 将 _site/ 推送到 deploy 分支。

你无需在本地维护 deploy 分支；合并到 main 后由 Actions 自动更新。

2. GitHub 仓库侧前提条件

2.1 允许 Actions 写入仓库内容

peaceiris/actions-gh-pages 需要使用默认的 GITHUB_TOKEN 向 deploy 分支推送提交。若组织或仓库将 Token 设为只读，推送会失败。

请在 GitHub 仓库页面：Settings → Actions → General → Workflow permissions 中，选择 Read and write permissions，并勾选 Allow GitHub Actions to create and approve pull requests（若需；仅推送分支时通常写权限即可）。

保存后重新运行一次失败的工作流即可。

2.2 首次运行

将包含该 workflow 的提交推送到 main 后，在 Actions 页签中应出现 Deploy static site to deploy branch。首次成功执行后，仓库中会出现 deploy 分支。

3. Cloudflare Pages 控制台配置（Git 集成）

以下在 Cloudflare Dashboard → Workers & Pages → Create → Pages → Connect to Git 中完成。

  1. 选择仓库：授权并选中 huhuaping/harness（或你的 fork / 组织仓库名）。
  2. 生产分支（Production branch）：设为 deploy。
  3. 构建设置（静态分支、无构建步骤）：
    • Framework preset：None（或等价「无框架」）。
    • Build command：留空，或填写 exit 0（表示不在 Cloudflare 侧再执行构建；真实构建已在 GitHub Actions 完成）。
    • Build output directory：填写 /（根目录），因为 deploy 分支根目录即为站点根，不是 _site 子目录。
  4. 保存并首次 Deploy。之后每次 deploy 分支被 Actions 更新，Cloudflare 会按需自动拉取并发布新版本。

3.1 预览分支（可选）

若希望 Pull Request 也有预览环境，可在 Pages 项目设置中启用 Preview deployments，并指定预览所用分支或 PR 策略（与 main / deploy 模型独立，按 Cloudflare 当前文档配置即可）。

3.2 自定义域名与 HTTPS

在 Cloudflare Pages 项目 → Custom domains 中添加域名，并按提示完成 DNS（通常同一 Zone 内可一键完成）。HTTPS 由 Cloudflare 自动处理。

4. 本地与 CI 行为对齐

  • 本地预览：quarto preview。
  • 与 CI 一致的全量构建：quarto render，产物目录为 _quarto.yml 中的 output-dir（本仓库为 _site）。
  • 若某次构建在 CI 失败（例如 Quarto 版本差异、未提交的必需文件），deploy 分支不会更新，线上仍为上一次成功版本。

5. 备选方案：Wrangler 直传（不使用 deploy 分支）

若你希望 不维护 Git 上的 deploy 分支，而由 CI 在构建后直接上传到 Cloudflare Pages，可使用官方 wrangler pages deploy _site，并配置 API Token 与 Account ID。该路径与本工作流 二选一 即可，避免同一站点两套发布源冲突。

简要步骤（仅作索引，具体以 Cloudflare Pages · Direct Upload 为准）：

  1. 在 Cloudflare 创建 API Token（含 Account、Pages 编辑权限）。
  2. 在 GitHub 仓库 Settings → Secrets and variables → Actions 中添加 CLOUDFLARE_API_TOKEN、CLOUDFLARE_ACCOUNT_ID，以及 Pages 项目名称 等变量。
  3. 在工作流中增加 wrangler pages deploy _site --project-name=<你的项目名> 步骤。

当前仓库默认采用 deploy 分支 + Pages Git 连接，便于在 GitHub 上直接查看已发布静态树与回滚历史。

6. 故障排查简表

现象 可能原因
Actions 报无权推送到 deploy 仓库 Workflow permissions 未设为 Read and write
Cloudflare 构建报找不到文件 生产分支误选为 main，或输出目录写成了 _site（在 deploy 上应为 /）
Cloudflare 在云端执行 quarto 失败 不应在 CF 侧执行 Quarto；将 Build command 留空，仅用 deploy 分支
页面样式丢失 检查 _quarto.yml 中资源路径是否为相对路径；本地 quarto render 后打开 _site/index.html 对比

7. 小结

  • GitHub Actions：在 main 上渲染，将 _site/ 同步到 deploy 分支根目录。
  • Cloudflare Pages：连接同一仓库，生产分支 = deploy，无构建命令，输出目录 = /。

按上述配置后，日常只需向 main 推送或合并 PR，即可在数分钟内完成静态站点更新。