本文记录一条最常用、维护成本最低的部署路线：GitHub + Cloudflare Pages 自动构建发布 Hugo 站点。

1. 准备工作

开始前确认以下条件：

  • 已有 Cloudflare 账号。
  • 已有 GitHub 仓库（包含你的 Hugo 站点代码）。
  • 本地可执行 Hugo 命令并能成功生成 public/。

本地构建示例：

hugo --gc --minify

如果命令执行成功，会在项目根目录生成 public/。

2. 推送 Hugo 项目到 GitHub

如果仓库还没有代码，先初始化并推送：

git init
git add .
git commit -m "init hugo site"
git branch -M main
git remote add origin <your-github-repo-url>
git push -u origin main

后续每次更新文章只需要常规提交：

git add .
git commit -m "publish new post"
git push

3. 在 Cloudflare Pages 创建项目

  1. 登录 Cloudflare 控制台。
  2. 进入 Workers & Pages。
  3. 点击 Create application，选择 Pages。
  4. 选择 Connect to Git，授权并绑定你的 GitHub 仓库。
  5. 选择部署分支（通常是 main）。

4. 填写 Hugo 构建配置

在构建设置页面填写：

  • Framework preset: Hugo
  • Build command: hugo --gc --minify
  • Build output directory: public

如果需要固定 Hugo 版本，可在环境变量中添加（可选）：

  • HUGO_VERSION = 0.152.2（按你实际使用版本填写）

保存后开始首次部署。

5. 验证部署结果

Cloudflare 会提供一个 *.pages.dev 域名。

验证以下内容：

  • 首页是否正常加载。
  • 文章详情页是否可访问。
  • 标签页 /tags/ 是否正常。
  • CSS/字体等静态资源是否加载成功。

6. 自动部署机制

完成上述配置后，每次 git push 到绑定分支都会触发 Cloudflare Pages 自动构建与发布。

建议把发布流程固定为：

  1. 本地写 Markdown 文章。
  2. 执行本地预览 hugo server。
  3. 提交并推送到 GitHub。
  4. 等待 Cloudflare 构建完成并在线检查。

7. 常见问题排查

构建失败

优先检查：

  • Hugo 版本是否匹配。
  • 构建命令是否写成 hugo --gc --minify。
  • 输出目录是否为 public。

页面样式丢失

优先检查：

  • baseURL 配置是否正确（自定义域名场景尤其注意）。
  • 静态资源路径是否写为绝对或可解析路径。
  • 最近是否修改了模板路径或资源管线。

标签页为空

优先检查：

  • 文章 front matter 是否包含 tags。
  • 文章是否为 draft: false。

8. 绑定自定义域名（可选）

在 Pages 项目内进入 Custom domains，添加你的域名并按提示配置 DNS。生效后 Cloudflare 会自动处理 HTTPS 证书。

完成后，你的 Hugo 博客就具备了“写 Markdown -> push -> 自动上线”的最简发布链路。