🚀 引言

在 2026 年，用 Cloudflare Pages（简称 CF Pages）来托管基于 Hugo 编译的 Markdown 静态博客，依然是地表最强、最具性价比的“白嫖”组合。它具备全球边缘节点秒开、完全免费、无限请求流量等绝对优势。

然而，随着 Cloudflare 推进控制台大改版，以及 Hugo 核心版本的迭代，许多互联网上的老教程已经变成了埋满地雷的“陈年旧坑”。本文真实记录了一次完整的踩坑与拨乱反正的破局全过程。

🎨 为什么选择 Hugo？

在横向对比了前端四大静态网站生成器（SSG）后，我们最终锁定了 Hugo：

  • Hugo (Go)：单文件无依赖，微秒级编译，生态成熟（如经典的极简高颜值主题 PaperMod）。
  • Astro / VitePress：虽然现代，但对纯粹写 Markdown 的技术博主来说，自由度过高导致配置相对繁琐。
  • Hexo (Node.js)：中文生态极强，但依赖沉重，且文章过百后编译速度断崖式下跌。

🛠️ 核心通关秘籍：那些老教程没告诉你的巨坑

坑一：新版 Hugo 默认安全策略导致本地“一片空白”

现象：本地引入主题（如 PaperMod）后运行 hugo server，页面竟然没有任何报错地渲染出纯白板。 破局：新版 Hugo 引入了严格的模块与执行安全限制。必须在根目录的 hugo.toml 底部显式授权：

[security]
  [security.exec]
    allow = ['^go$', '^npx$', '^postcss$']
  [security.modules]
    allow = ['os', 'getenv']

坑二：私有仓库克隆时 Git Submodule “人间蒸发”

现象：线上编译报 error calling partial: partial "head.html" not found。 破局：

  1. 确保本地项目根目录下的 .gitmodules 配置文件中，主题的克隆 URL 必须是 HTTPS 格式，绝对不能是 SSH 格式（因为 CF 没有你的私有 SSH 密钥）：
[submodule "themes/PaperMod"]
    path = themes/PaperMod
    url = [https://github.com/adityatelange/hugo-PaperMod.git](https://github.com/adityatelange/hugo-PaperMod.git)
  1. 必须在 Cloudflare 构建环境变量中显式传入 GIT_SUBMODULES = true，强制构建引擎深度克隆子模块。

坑三：主题嫌弃 Cloudflare 默认 Hugo 版本过低

现象：CF 线上构建日志爆红：ERROR => hugo v0.146.0 or greater is required for hugo-PaperMod to build。 破局：Cloudflare Pages 默认的编译器版本较为古老。需要在 CF 环境变量中手动锁定一个极其现代的稳定版本，添加环境变量：HUGO_VERSION = 0.150.0。

🤯 终极对决：Cloudflare 2026 改版 UI 的“捉迷藏”

这是最让人抓狂的环节。在 2026 年最新的 Cloudflare 控制台中，原有的 Workers 和 Pages 入口被深度融合。

1. 误入 Workers 的限流陷阱

如果顺着默认引导点击 Create application，绑定 Git 仓库，CF 会默认将你引导至 “Create a Worker” 的流里。

  • Workers 架构的硬伤：免费版每天严格限制 10 万次请求（Requests today: 100,000）。一旦博客图片稍多、或者遭遇恶意刷量，网站会瞬间报 1101 Error 宕机。
  • Pages 架构的真香：完全不限量！ 纯静态边缘分发，无惧任何 DDoS 流量。

2. 把 Pages 入口找出来！

在 “Create a Worker / Select a repository” 选完 GitHub 仓库的页面，千万不要盲目点蓝色 Next！ 把页面死死拉到最底部，在极其隐蔽的角落里，找到那行产品经理故意藏起来的小字：

“Looking for Cloudflare Pages? Deploy a static site instead”

点击那行小字里的 Pages 链接，才能顺利切换回正宗的 Pages 部署逻辑！

📝 最终 Cloudflare 完美线上配置快照

当你成功潜入正宗的 Pages 页面后，请确保你的参数与下方配置完全对齐：

⚙️ Build configuration (构建配置)

  • Framework preset: Hugo
  • Build command: hugo
  • Build output directory: public
  • Root directory: /

🔐 Variables and secrets (环境变量)

  • HUGO_VERSION = 0.150.0 (锁死高版本，解除主题限制)
  • GIT_SUBMODULES = true (开启子模块拉取，避免丢失样式)

🎯 成果见证

配置对齐、环境变量保存、点击 Retry deployment。 伴随着构建日志刷刷闪过，久违的大绿勾（Success） 终于亮起！Cloudflare 随即分发了一个专属的 *.pages.dev 域名。

至此，一个纯私有源码托管、零服务器成本、无限流量、全球边缘秒开的完美 Hugo 技术博客正式宣告落成。

写下此文，致敬所有在 Cloudflare 迷宫般的新版 UI 里，嘴里骂着“操”却依然死磕到底的开发者们。