# 用 Cloudflare Pages 免费发布 Hugo 网站

- Canonical: https://bumai.org/experience/cloudflare-pages-hugo/
- Published: 2026-07-16
- Updated: 2026-07-16
- Difficulty: 新手
- Tags: Hugo, Cloudflare

> 本文可能随软件和服务版本变化。引用或执行前请检查更新时间与适用环境。


如果你在用 AI 帮你写代码（也就是 vibe coding），大概率会在某个阶段想要一个真实的网址，能发给朋友，也能被搜索引擎找到。这篇记录的是最省钱、最少踩坑的一条路：**Hugo 生成静态网站，Cloudflare Pages 免费托管**。全程不需要服务器，也不需要信用卡。

## 为什么选这个组合

先说清楚为什么不是别的方案，省得你多绕路。

Hugo 是一个静态网站生成器：你写 Markdown 文件，它编译成纯 HTML。没有数据库,没有后端进程,打开速度极快,搜索引擎也容易读懂。对于博客、文档、个人主页这类"内容不常变、访问量不算特别大"的网站,这是最省心的选择。

Cloudflare Pages 是免费的静态网站托管服务,直接连你的 GitHub 仓库,每次 `git push` 自动重新构建和发布。免费额度对个人项目完全够用,而且自带全球 CDN 和免费 HTTPS。

如果你的网站需要用户登录、评论区、数据库,这条路就不适合了——那时候该考虑 Next.js 加数据库之类的方案。但如果只是想要一个能打开、能被搜到的网站,不要一开始就上重型框架。

## 开始前先确认

动手之前,确认三件事,能省掉后面大部分的排查时间:

- 本地能运行 `git` 命令,并且已经登录 GitHub。
- 有一个域名(可选,没有域名也能先用 Cloudflare Pages 分配的免费子域名)。
- 知道自己的仓库结构——尤其是 Hugo 项目的根目录在哪里,后面配置构建时要填这个路径。

## 第一步:让 Hugo 能在本地跑起来

先确认 Hugo 装好了:

```bash
hugo version
```

如果没输出版本号,去 Hugo 官方 GitHub Releases 下载对应系统的二进制文件,或者用系统包管理器安装。装好之后,在项目根目录跑一次本地预览:

```bash
hugo server -D
```

`-D` 表示连草稿(draft)也一起显示,方便你在发布前检查。浏览器打开 `http://localhost:1313` 应该就能看到网站了。如果这一步报错,大概率是 `hugo.toml`(或 `config.toml`)里的路径配置有问题,先解决这个,再往下走。

## 第二步:把项目推到 GitHub

如果还没有仓库,新建一个,然后:

```bash
git init
git add .
git commit -m "Initial Hugo site"
git branch -M main
git remote add origin git@github.com:你的用户名/你的仓库名.git
git push -u origin main
```

注意一点:**不要把 `public/` 目录提交进仓库**。这是 Hugo 编译后生成的文件夹,Cloudflare Pages 会自己重新生成,提交进去只会造成冗余和冲突。在 `.gitignore` 里加一行:

```text
public/
```

## 第三步:在 Cloudflare Pages 里连接仓库

登录 Cloudflare 控制台,进入 Pages,选择"连接到 Git",授权访问你的 GitHub 账号,选中刚才的仓库。

到了构建配置这一步,大部分踩坑都发生在这里,填对下面几项就没问题:

```text
框架预设:         Hugo
构建命令:         hugo --gc --minify
构建输出目录:     public
根目录:           留空(除非你的 Hugo 项目不在仓库根目录)
```

> [!NOTE]
> Cloudflare Pages 默认的 Hugo 版本可能比你本地的旧。如果构建报错提示某个功能不支持,在环境变量里加一个 `HUGO_VERSION`,值填你本地 `hugo version` 看到的版本号,比如 `0.134.3`。

保存之后,Cloudflare 会自动拉取代码、执行构建命令、把 `public/` 目录里的内容发布出去。第一次构建通常需要一两分钟。

## 第四步:绑定自定义域名

如果你有自己的域名,在 Pages 项目里进入"自定义域",输入域名,Cloudflare 会告诉你需要添加的 DNS 记录(通常是一条 CNAME)。如果域名本身也托管在 Cloudflare,这一步几乎是自动完成的;如果域名在别的服务商,需要手动去那边加一条记录。

DNS 生效通常几分钟到几十分钟,取决于你之前设置的 TTL。心急没用,喝杯茶等它传播。

## 第五步:验证,别急着关电脑

发布完成不代表万事大吉,花两分钟确认这几件事:

- 打开正式域名,不是 Cloudflare 给的临时域名,确认页面内容和本地预览一致。
- 打开 `/robots.txt`,应该返回纯文本,不是首页 HTML。
- 打开 `/sitemap.xml`,应该返回 XML,不是 404 或者首页。
- 用手机打开一次,检查是不是意外触发了某个只在桌面测试过的样式。
- 改一行文字,`git push`,确认 Cloudflare 真的会自动重新构建——这是"自动部署"最值得验证的部分,而不是假设它会生效。

> [!WARNING]
> 如果 `/robots.txt` 或 `/sitemap.xml` 返回的是首页内容,通常是因为 Hugo 配置里禁用了对应的输出类型,或者 Cloudflare Pages 把所有未知路径都重定向回了首页。检查 `hugo.toml` 里的 `disableKinds`,确认没有把 `sitemap` 或 `robotsTXT` 也一起关掉。

## 之后要做的事

网站上线只是起点。日常维护其实很轻:写新内容时加一个 Markdown 文件,`git push`,Cloudflare 自动构建发布,不需要手动上传任何东西。真正需要留意的是构建日志——如果哪次 push 之后网站没更新,第一时间去 Cloudflare Pages 的部署记录里看构建有没有报错,而不是干等着刷新页面。

这套流程从头搭建大概花一个下午,之后每次更新只需要一次 `git push`。对于想要真实网址、又不想背运维负担的 vibe coding 项目,这是目前最划算的组合。