用落笔一键发布博客：Hugo、GitHub 与 Cloudflare Pages 搭建指南

这是一份面向普通用户的博客搭建教程。完成后，你可以在落笔中写作，并把文章一键发布到自己的 GitHub + Hugo + Cloudflare Pages 博客。

这套方案最终能做什么

完成一次初始化后，日常发布只需要：

1. 在落笔中写完或修改文章；
2. 点击“发布到博客”或“更新”；
3. 落笔把文章推送到自己的 GitHub 博客仓库；
4. Cloudflare Pages 自动构建并更新网站。

第一次搭建需要配置账号和授权；之后不需要再手工操作 GitHub 或 Cloudflare。

一、整体架构

flowchart LR
    A["落笔：写作与发布入口"] --> B["GitHub：博客源码仓库"]
    B --> C["Cloudflare Pages：自动构建与托管"]
    C --> D["pages.dev 或自定义域名"]
    E["Hugo：静态网站生成器"] --> C
    B --> E

四个部分各自负责不同工作：

部分	作用
Hugo	把 Markdown 文章、主题和配置文件生成静态网站
GitHub	保存博客源码、文章、图片和版本历史
Cloudflare Pages	监听 GitHub，在代码变化后自动运行 Hugo 并托管网站
落笔	提供写作、文章整理和“一键发布到博客”的入口

发布数据流

落笔中的 Markdown
    ↓
发布到已配置的 GitHub 仓库
    ↓
GitHub main 分支产生新提交
    ↓
Cloudflare Pages 检测到提交
    ↓
运行 Hugo，生成 public/
    ↓
更新 pages.dev 和自定义域名

两个需要分别授权的平台连接

Cloudflare 和落笔都需要访问 GitHub，但它们是两次独立授权：

• Cloudflare 需要读取 GitHub 仓库，用于构建和部署；
• 落笔需要向目标 GitHub 仓库推送文章。

不要把 GitHub 密码、PAT、OAuth Token 或 Cloudflare API Token 写进 Hugo 配置、文章、提示词或 GitHub 仓库。需要授权时，按页面提示使用官方授权流程。

二、GitHub 仓库应该如何组织

建议为博客建立一个独立 GitHub 仓库，例如：

my-blog/
├── hugo.toml
├── content/
│   ├── _index.md
│   └── posts/
│       ├── _index.md
│       └── first-post/
│           ├── index.md
│           └── cover.png
├── themes/
│   └── <主题名称>/
├── layouts/
├── static/
├── assets/
├── .gitignore
└── README.md

目录用途

路径	用途
hugo.toml	Hugo 网站名称、域名、语言、主题和功能配置
content/	网站内容源文件
content/posts/	博客文章统一目录
content/posts//	一篇文章及其图片组成的文章包
themes/	Hugo 主题；主题必须能在干净环境中使用
layouts/	覆盖主题模板的位置
static/	直接复制到网站根目录的静态文件
assets/	需要 Hugo 处理的样式、脚本或资源
public/	Hugo 构建产物，通常不作为源码维护

文章为什么使用文件夹

每篇文章使用 Hugo 的 leaf bundle 结构：

content/posts/my-first-post/
├── index.md
├── cover.png
└── diagram.png

这样正文和图片天然属于同一篇文章，移动、备份和发布时不容易丢失资源。文件夹名称就是文章的 URL slug，例如：

content/posts/my-first-post/
→ https://blog.example.com/posts/my-first-post/

第一次发布后不要随意修改 slug，否则文章地址会改变，后续更新也可能变成另一篇文章。

三、Hugo 配置需要设置什么

hugo.toml 至少需要明确以下字段：

baseURL = 'https://blog.example.com/'
languageCode = 'zh-cn'
title = '我的博客'
theme = 'PaperMod'

[params]
  mainSections = ['posts']

字段说明

字段	设置规则
baseURL	填写最终网站地址，替换成自己的域名，并保留结尾斜杠
languageCode	例如 zh-cn、en-us
title	网站名称
theme	已安装并提交到仓库的主题名称
params.mainSections	博客文章目录，建议设置为 posts

主题可以使用 PaperMod，也可以使用其他 Hugo 主题。无论选择哪个主题，都要确保：

• 主题代码或模块版本已经固定；
• Cloudflare 的构建环境可以取得主题；
• 本地执行 hugo –gc –minify 可以成功；
• GitHub 新建 checkout 后仍然可以成功构建。

四、文章 Front Matter 如何设置

一篇标准文章的 index.md 可以这样写：

---
title: "我的第一篇文章"
date: 2026-08-05
draft: false
tags:
  - 写作
  - Hugo
description: "一段可选的文章摘要"
---

正文从这里开始。

字段	是否必需	说明
title	建议必需	文章标题
date	建议必需	发布日期，使用 YYYY-MM-DD
draft	建议必需	false 才会进入正式构建
tags	可选	标签列表
description	可选	文章自己的摘要
cover	主题相关	主题支持封面时再配置

没有文章摘要时，直接省略 description，不要用项目介绍或默认宣传语代替。

五、Cloudflare Pages 如何配置

1. 创建 Pages 项目

在 Cloudflare 控制台进入：

Workers & Pages
→ Create application
→ Pages
→ Connect to Git

选择 GitHub，授权 Cloudflare 访问博客仓库，然后选择刚才创建的 GitHub 仓库。

2. 设置构建参数

Cloudflare Pages 字段	推荐值
Production branch	main
Build command	hugo –gc –minify
Build output directory	public
Root directory	/；如果是 monorepo，则填写 Hugo 项目所在目录
HUGO_VERSION	与本地验证通过的 Hugo 版本一致

Hugo 默认把网站生成到项目根目录的 public/。Cloudflare Pages 应该发布这个目录，而不是 content/ 或 Hugo 源码目录。

3. 绑定域名

首次部署成功后，Cloudflare 会提供一个 pages.dev 地址。确认这个地址可以打开后，再进入：

Pages 项目
→ Custom domains
→ Set up a domain

填入自己的正式域名，例如 https://blog.example.com。

如果使用子域名，需要按 Cloudflare 提示配置 CNAME；如果使用根域名，需要把域名接入对应 Cloudflare Zone。域名配置完成后，把同一个地址写回 hugo.toml 的 baseURL。

4. 验证自动部署

在 GitHub 修改一个非敏感的页面配置并推送到 main，确认：

1. GitHub 提交旁边出现 Cloudflare Pages 构建状态；
2. Cloudflare Pages 生成新的 Production deployment；
3. pages.dev 和自定义域名都能打开新内容。

Cloudflare Pages 还可以为 Pull Request 和其他分支生成预览地址。正式博客使用 main，测试改动可以先走预览。

六、把搭建过程交给 AI Agent

AI Agent 的职责是：

• 询问缺少的配置；
• 创建 Hugo 文件和目录；
• 检查本地构建；
• 帮用户准备 GitHub 仓库；
• 引导用户完成 Cloudflare 授权和设置；
• 最后引导用户在落笔中绑定博客。

AI Agent 不应该：

• 索要或保存密码、PAT、OAuth Token；
• 在没有权限时声称已经创建 GitHub 仓库；
• 在没有 Cloudflare 页面证据时声称已经部署成功；
• 擅自把用户的文章发布到别人的仓库或域名；
• 创建一套与 Cloudflare Pages 并行的服务器或 GitHub Actions 流程。

七、可以直接复制给 AI Agent 的主提示词

将下面整段内容复制给支持终端、文件编辑或浏览器操作的 AI Agent。没有这些工具时，Agent 应把命令和点击路径写出来，由用户手动执行。

你是我的博客搭建向导和工程实施 Agent。请带我从零搭建一套“落笔（Loby）一键发布到我的博客”的完整流程。

目标架构：
- Hugo：生成静态博客网站；
- GitHub：保存 Hugo 源码、文章、图片和版本历史；
- Cloudflare Pages：连接 GitHub，在 main 分支变化后自动构建和部署；
- 落笔：作为日常写作和一键发布入口。

我的配置：
- 博客名称：{{BLOG_NAME}}
- GitHub 用户名或组织：{{GITHUB_OWNER}}
- GitHub 仓库名：{{GITHUB_REPO}}
- 正式网站地址：{{SITE_URL}}
- 网站语言：{{LANGUAGE_CODE}}
- Hugo 主题：{{HUGO_THEME}}
- 落笔写作库路径：{{LOBY_LIBRARY_PATH}}
- 本机系统：{{OPERATING_SYSTEM}}

工作规则：
1. 先检查我提供的信息是否完整，只询问缺少的必要信息。
2. 如果你有终端工具，就检查 git、hugo、gh、wrangler 是否可用；如果没有，就给我可复制的命令。
3. 如果你有文件编辑能力，就在指定目录生成文件；如果目录已有文件，先读取并保护现有内容，不要直接覆盖。
4. 所有需要登录、授权或绑定域名的操作，都必须明确告诉我需要在浏览器中点击什么；没有真实成功结果前，不要说“已完成”。
5. 绝不索要、回显、保存或提交 GitHub 密码、PAT、OAuth Token、Cloudflare API Token 或其他秘密。
6. 不使用 GitHub Actions、服务器或第二套发布服务，除非我明确要求。默认使用 Cloudflare Pages 的 GitHub 集成。
7. 所有路径、仓库名、域名、标题和语言都使用我的配置，不要使用示例账号或别人的域名。

请按以下阶段执行：

阶段 1：确认方案
- 解释 Hugo、GitHub、Cloudflare Pages 和落笔各自负责什么。
- 输出一张简短的数据流图。
- 列出还缺少的用户输入。

阶段 2：创建 Hugo 博客
- 创建 hugo.toml。
- 设置 baseURL、languageCode、title、theme 和 content/posts 文章目录。
- 创建 content/_index.md 和 content/posts/_index.md。
- 创建 themes、layouts、static、assets 等必要目录；主题必须在干净环境可以获得。
- 创建 .gitignore，忽略 public、Hugo 缓存、系统临时文件和本地秘密文件。
- 创建 README.md，写清本地预览、构建和 Loby 发布方式。
- 文章使用以下结构：
  content/posts/<slug>/index.md
  content/posts/<slug>/图片文件
- 不要创建依赖本机绝对路径的配置。

阶段 3：本地验证
- 执行 hugo version。
- 执行 hugo --gc --minify。
- 如有问题，先修复真实错误，再继续。
- 告诉我 Hugo 版本、构建结果和生成目录。

阶段 4：GitHub
- 如果我还没有仓库，指导我创建 {{GITHUB_OWNER}}/{{GITHUB_REPO}}。
- 将博客源码推送到 main。
- 推送前检查 git status、远程地址、敏感文件和构建结果。
- 如果你没有 GitHub 权限，停下来告诉我完成授权的具体步骤。
- 最终报告 GitHub 仓库地址和 main 的提交信息。

阶段 5：Cloudflare Pages
- 指导我进入 Workers & Pages → Create application → Pages → Connect to Git。
- 连接 GitHub 并选择 {{GITHUB_OWNER}}/{{GITHUB_REPO}}。
- 设置：
  Production branch = main
  Build command = hugo --gc --minify
  Build output directory = public
  Root directory = /
  HUGO_VERSION = 本地验证通过的 Hugo 版本
- 指导我在 Pages → Custom domains 中绑定 {{SITE_URL}}。
- 说明 DNS 需要如何配置。
- 等待我完成授权和域名操作，不要假装替我完成。
- 验证 pages.dev 地址、Production deployment 和正式域名。

阶段 6：落笔
- 指导我打开落笔“设置 → 发布 → 发布目标”。
- 点击“添加发布目标 → GitHub”，按页面完成 GitHub 官方授权。
- 点击“添加 GitHub 发布目标 → Hugo 博客”。
- 指导我填写：
  目标名称 = {{BLOG_NAME}}
  GitHub 仓库 = {{GITHUB_OWNER}}/{{GITHUB_REPO}}
  发布分支 = main
  文章目录 = content/posts
  网站地址 = {{SITE_URL}}
- 指导我在项目设置中绑定这个发布目标。
- 不要让我手工编辑落笔的内部配置文件或秘密存储。

阶段 7：真实冒烟测试
- 让我在落笔中创建一篇短测试文章。
- 使用“发布到博客”执行一次发布。
- 检查 GitHub 是否出现新文章文件夹和文章文件。
- 检查 Cloudflare 是否产生新的构建和 Production deployment。
- 检查最终文章 URL 是否可以打开。
- 再修改同一篇文章并点击“更新”，确认文章地址没有变化。

最终请交付：
1. 博客目录树；
2. hugo.toml 的关键字段说明；
3. GitHub 仓库设置；
4. Cloudflare Pages 构建设置；
5. 落笔需要填写的字段；
6. 本地、GitHub、Cloudflare 和文章 URL 的验收结果；
7. 一份故障排查表，至少覆盖 Hugo 构建失败、主题缺失、GitHub 授权失败、Cloudflare 构建失败、DNS 未生效、文章 draft=true 和落笔文章目录配置错误。

八、落笔中的日常发布流程

博客初始化完成后，用户不需要再打开终端：

落笔中完成文章
    ↓
确认标题、标签、封面和文章状态
    ↓
点击“发布到博客”
    ↓
确认发布目标
    ↓
等待 GitHub 和 Cloudflare 完成
    ↓
打开文章链接检查

更新文章时，直接在落笔中修改原文并点击“更新”。不要在 GitHub 网页端复制粘贴文章，也不要随意改文章文件夹名称。

九、常见错误

现象	优先检查
Cloudflare 找不到文章	Build output 是否为 public，文章是否在 content/posts
Hugo 本地能构建，Cloudflare 失败	Hugo 版本、主题依赖、主题是否已提交到 GitHub
页面能打开但链接不对	hugo.toml 的 baseURL 是否仍是示例域名
落笔找不到仓库	落笔 GitHub 授权是否包含目标仓库
发布后文章没有出现	draft 是否为 true，Cloudflare 构建是否成功
域名无法访问	Pages 自定义域名是否已关联，DNS/CNAME 是否正确
更新变成了新文章	是否修改了文章文件夹名称或 slug

官方参考

• Cloudflare Pages Git integration: https://developers.cloudflare.com/pages/configuration/git-integration/
• Cloudflare Pages GitHub integration: https://developers.cloudflare.com/pages/configuration/git-integration/github-integration/
• Cloudflare Pages Hugo guide: https://developers.cloudflare.com/pages/framework-guides/deploy-a-hugo-site/
• Cloudflare Pages custom domains: https://developers.cloudflare.com/pages/configuration/custom-domains/
• Hugo page bundles: https://gohugo.io/content-management/page-bundles/
• Hugo quick start: https://gohugo.io/getting-started/quick-start/