[{"content":"🚀 引言 在 2026 年，用 Cloudflare Pages（简称 CF Pages）来托管基于 Hugo 编译的 Markdown 静态博客，依然是地表最强、最具性价比的“白嫖”组合。它具备全球边缘节点秒开、完全免费、无限请求流量等绝对优势。\n然而，随着 Cloudflare 推进控制台大改版，以及 Hugo 核心版本的迭代，许多互联网上的老教程已经变成了埋满地雷的“陈年旧坑”。本文真实记录了一次完整的踩坑与拨乱反正的破局全过程。\n🎨 为什么选择 Hugo？ 在横向对比了前端四大静态网站生成器（SSG）后，我们最终锁定了 Hugo：\nHugo (Go)：单文件无依赖，微秒级编译，生态成熟（如经典的极简高颜值主题 PaperMod）。 Astro / VitePress：虽然现代，但对纯粹写 Markdown 的技术博主来说，自由度过高导致配置相对繁琐。 Hexo (Node.js)：中文生态极强，但依赖沉重，且文章过百后编译速度断崖式下跌。 🛠️ 核心通关秘籍：那些老教程没告诉你的巨坑 坑一：新版 Hugo 默认安全策略导致本地“一片空白” 现象：本地引入主题（如 PaperMod）后运行 hugo server，页面竟然没有任何报错地渲染出纯白板。 破局：新版 Hugo 引入了严格的模块与执行安全限制。必须在根目录的 hugo.toml 底部显式授权：\n[security] [security.exec] allow = [\u0026#39;^go$\u0026#39;, \u0026#39;^npx$\u0026#39;, \u0026#39;^postcss$\u0026#39;] [security.modules] allow = [\u0026#39;os\u0026#39;, \u0026#39;getenv\u0026#39;] 坑二：私有仓库克隆时 Git Submodule “人间蒸发” 现象：线上编译报 error calling partial: partial \u0026quot;head.html\u0026quot; not found。 破局：\n确保本地项目根目录下的 .gitmodules 配置文件中，主题的克隆 URL 必须是 HTTPS 格式，绝对不能是 SSH 格式（因为 CF 没有你的私有 SSH 密钥）： [submodule \u0026#34;themes/PaperMod\u0026#34;] path = themes/PaperMod url = [https://github.com/adityatelange/hugo-PaperMod.git](https://github.com/adityatelange/hugo-PaperMod.git) 必须在 Cloudflare 构建环境变量中显式传入 GIT_SUBMODULES = true，强制构建引擎深度克隆子模块。 坑三：主题嫌弃 Cloudflare 默认 Hugo 版本过低 现象：CF 线上构建日志爆红：ERROR =\u0026gt; hugo v0.146.0 or greater is required for hugo-PaperMod to build。 破局：Cloudflare Pages 默认的编译器版本较为古老。需要在 CF 环境变量中手动锁定一个极其现代的稳定版本，添加环境变量：HUGO_VERSION = 0.150.0。\n🤯 终极对决：Cloudflare 2026 改版 UI 的“捉迷藏” 这是最让人抓狂的环节。在 2026 年最新的 Cloudflare 控制台中，原有的 Workers 和 Pages 入口被深度融合。\n1. 误入 Workers 的限流陷阱 如果顺着默认引导点击 Create application，绑定 Git 仓库，CF 会默认将你引导至 \u0026ldquo;Create a Worker\u0026rdquo; 的流里。\nWorkers 架构的硬伤：免费版每天严格限制 10 万次请求（Requests today: 100,000）。一旦博客图片稍多、或者遭遇恶意刷量，网站会瞬间报 1101 Error 宕机。 Pages 架构的真香：完全不限量！ 纯静态边缘分发，无惧任何 DDoS 流量。 2. 把 Pages 入口找出来！ 在 “Create a Worker / Select a repository” 选完 GitHub 仓库的页面，千万不要盲目点蓝色 Next！ 把页面死死拉到最底部，在极其隐蔽的角落里，找到那行产品经理故意藏起来的小字：\n“Looking for Cloudflare Pages? Deploy a static site instead”\n点击那行小字里的 Pages 链接，才能顺利切换回正宗的 Pages 部署逻辑！\n📝 最终 Cloudflare 完美线上配置快照 当你成功潜入正宗的 Pages 页面后，请确保你的参数与下方配置完全对齐：\n⚙️ 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 域名。\n至此，一个纯私有源码托管、零服务器成本、无限流量、全球边缘秒开的完美 Hugo 技术博客正式宣告落成。\n写下此文，致敬所有在 Cloudflare 迷宫般的新版 UI 里，嘴里骂着“操”却依然死磕到底的开发者们。\n","permalink":"https://blog.162015.xyz/posts/cloudflare-pages-hugo-trap/","summary":"\u003ch3 id=\"-引言\"\u003e🚀 引言\u003c/h3\u003e\n\u003cp\u003e在 2026 年，用 \u003cstrong\u003eCloudflare Pages\u003c/strong\u003e（简称 CF Pages）来托管基于 \u003cstrong\u003eHugo\u003c/strong\u003e 编译的 Markdown 静态博客，依然是地表最强、最具性价比的“白嫖”组合。它具备\u003cstrong\u003e全球边缘节点秒开、完全免费、无限请求流量\u003c/strong\u003e等绝对优势。\u003c/p\u003e\n\u003cp\u003e然而，随着 Cloudflare 推进控制台大改版，以及 Hugo 核心版本的迭代，许多互联网上的老教程已经变成了埋满地雷的“陈年旧坑”。本文真实记录了一次完整的踩坑与拨乱反正的破局全过程。\u003c/p\u003e\n\u003chr\u003e\n\u003ch3 id=\"-为什么选择-hugo\"\u003e🎨 为什么选择 Hugo？\u003c/h3\u003e\n\u003cp\u003e在横向对比了前端四大静态网站生成器（SSG）后，我们最终锁定了 \u003cstrong\u003eHugo\u003c/strong\u003e：\u003c/p\u003e\n\u003cul\u003e\n\u003cli\u003e\u003cstrong\u003eHugo (Go)\u003c/strong\u003e：单文件无依赖，微秒级编译，生态成熟（如经典的极简高颜值主题 \u003ccode\u003ePaperMod\u003c/code\u003e）。\u003c/li\u003e\n\u003cli\u003e\u003cstrong\u003eAstro / VitePress\u003c/strong\u003e：虽然现代，但对纯粹写 Markdown 的技术博主来说，自由度过高导致配置相对繁琐。\u003c/li\u003e\n\u003cli\u003e\u003cstrong\u003eHexo (Node.js)\u003c/strong\u003e：中文生态极强，但依赖沉重，且文章过百后编译速度断崖式下跌。\u003c/li\u003e\n\u003c/ul\u003e\n\u003chr\u003e\n\u003ch3 id=\"-核心通关秘籍那些老教程没告诉你的巨坑\"\u003e🛠️ 核心通关秘籍：那些老教程没告诉你的巨坑\u003c/h3\u003e\n\u003ch4 id=\"坑一新版-hugo-默认安全策略导致本地一片空白\"\u003e坑一：新版 Hugo 默认安全策略导致本地“一片空白”\u003c/h4\u003e\n\u003cp\u003e\u003cstrong\u003e现象\u003c/strong\u003e：本地引入主题（如 \u003ccode\u003ePaperMod\u003c/code\u003e）后运行 \u003ccode\u003ehugo server\u003c/code\u003e，页面竟然没有任何报错地渲染出纯白板。\n\u003cstrong\u003e破局\u003c/strong\u003e：新版 Hugo 引入了严格的模块与执行安全限制。必须在根目录的 \u003ccode\u003ehugo.toml\u003c/code\u003e 底部显式授权：\u003c/p\u003e\n\u003cdiv class=\"highlight\"\u003e\u003cpre tabindex=\"0\" class=\"chroma\"\u003e\u003ccode class=\"language-toml\" data-lang=\"toml\"\u003e\u003cspan class=\"line\"\u003e\u003cspan class=\"cl\"\u003e\u003cspan class=\"p\"\u003e[\u003c/span\u003e\u003cspan class=\"nx\"\u003esecurity\u003c/span\u003e\u003cspan class=\"p\"\u003e]\u003c/span\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan class=\"line\"\u003e\u003cspan class=\"cl\"\u003e  \u003cspan class=\"p\"\u003e[\u003c/span\u003e\u003cspan class=\"nx\"\u003esecurity\u003c/span\u003e\u003cspan class=\"p\"\u003e.\u003c/span\u003e\u003cspan class=\"nx\"\u003eexec\u003c/span\u003e\u003cspan class=\"p\"\u003e]\u003c/span\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan class=\"line\"\u003e\u003cspan class=\"cl\"\u003e    \u003cspan class=\"nx\"\u003eallow\u003c/span\u003e \u003cspan class=\"p\"\u003e=\u003c/span\u003e \u003cspan class=\"p\"\u003e[\u003c/span\u003e\u003cspan class=\"s1\"\u003e\u0026#39;^go$\u0026#39;\u003c/span\u003e\u003cspan class=\"p\"\u003e,\u003c/span\u003e \u003cspan class=\"s1\"\u003e\u0026#39;^npx$\u0026#39;\u003c/span\u003e\u003cspan class=\"p\"\u003e,\u003c/span\u003e \u003cspan class=\"s1\"\u003e\u0026#39;^postcss$\u0026#39;\u003c/span\u003e\u003cspan class=\"p\"\u003e]\u003c/span\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan class=\"line\"\u003e\u003cspan class=\"cl\"\u003e  \u003cspan class=\"p\"\u003e[\u003c/span\u003e\u003cspan class=\"nx\"\u003esecurity\u003c/span\u003e\u003cspan class=\"p\"\u003e.\u003c/span\u003e\u003cspan class=\"nx\"\u003emodules\u003c/span\u003e\u003cspan class=\"p\"\u003e]\u003c/span\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan class=\"line\"\u003e\u003cspan class=\"cl\"\u003e    \u003cspan class=\"nx\"\u003eallow\u003c/span\u003e \u003cspan class=\"p\"\u003e=\u003c/span\u003e \u003cspan class=\"p\"\u003e[\u003c/span\u003e\u003cspan class=\"s1\"\u003e\u0026#39;os\u0026#39;\u003c/span\u003e\u003cspan class=\"p\"\u003e,\u003c/span\u003e \u003cspan class=\"s1\"\u003e\u0026#39;getenv\u0026#39;\u003c/span\u003e\u003cspan class=\"p\"\u003e]\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\u003c/div\u003e\n\u003ch4 id=\"坑二私有仓库克隆时-git-submodule-人间蒸发\"\u003e坑二：私有仓库克隆时 Git Submodule “人间蒸发”\u003c/h4\u003e\n\u003cp\u003e\u003cstrong\u003e现象\u003c/strong\u003e：线上编译报 \u003ccode\u003eerror calling partial: partial \u0026quot;head.html\u0026quot; not found\u003c/code\u003e。\n\u003cstrong\u003e破局\u003c/strong\u003e：\u003c/p\u003e\n\u003col\u003e\n\u003cli\u003e确保本地项目根目录下的 \u003ccode\u003e.gitmodules\u003c/code\u003e 配置文件中，主题的克隆 URL 必须是 \u003cstrong\u003eHTTPS 格式\u003c/strong\u003e，绝对不能是 SSH 格式（因为 CF 没有你的私有 SSH 密钥）：\u003c/li\u003e\n\u003c/ol\u003e\n\u003cdiv class=\"highlight\"\u003e\u003cpre tabindex=\"0\" class=\"chroma\"\u003e\u003ccode class=\"language-ini\" data-lang=\"ini\"\u003e\u003cspan class=\"line\"\u003e\u003cspan class=\"cl\"\u003e\u003cspan class=\"k\"\u003e[submodule \u0026#34;themes/PaperMod\u0026#34;]\u003c/span\u003e\n\u003c/span\u003e\u003c/span\u003e\u003cspan class=\"line\"\u003e\u003cspan class=\"cl\"\u003e    \u003cspan class=\"na\"\u003epath\u003c/span\u003e \u003cspan class=\"o\"\u003e=\u003c/span\u003e \u003cspan class=\"s\"\u003ethemes/PaperMod\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003cspan class=\"line\"\u003e\u003cspan class=\"cl\"\u003e\u003cspan class=\"s\"\u003e    url = [https://github.com/adityatelange/hugo-PaperMod.git](https://github.com/adityatelange/hugo-PaperMod.git)\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\u003c/div\u003e\n\u003col start=\"2\"\u003e\n\u003cli\u003e必须在 Cloudflare 构建环境变量中显式传入 \u003ccode\u003eGIT_SUBMODULES = true\u003c/code\u003e，强制构建引擎深度克隆子模块。\u003c/li\u003e\n\u003c/ol\u003e\n\u003ch4 id=\"坑三主题嫌弃-cloudflare-默认-hugo-版本过低\"\u003e坑三：主题嫌弃 Cloudflare 默认 Hugo 版本过低\u003c/h4\u003e\n\u003cp\u003e\u003cstrong\u003e现象\u003c/strong\u003e：CF 线上构建日志爆红：\u003ccode\u003eERROR =\u0026gt; hugo v0.146.0 or greater is required for hugo-PaperMod to build\u003c/code\u003e。\n\u003cstrong\u003e破局\u003c/strong\u003e：Cloudflare Pages 默认的编译器版本较为古老。需要在 CF 环境变量中手动锁定一个极其现代的稳定版本，添加环境变量：\u003ccode\u003eHUGO_VERSION = 0.150.0\u003c/code\u003e。\u003c/p\u003e","title":"踩坑记录：2026版 Cloudflare Pages 部署 Hugo 静态博客全策略"},{"content":"一个记录技术折腾、AI 探索与生活思考的个人博客。\n使用 Hugo + PaperMod 构建 部署在 Cloudflare Pages 博客源码托管在 GitHub 联系我：hi@162015.xyz\n","permalink":"https://blog.162015.xyz/about/","summary":"\u003cp\u003e一个记录技术折腾、AI 探索与生活思考的个人博客。\u003c/p\u003e\n\u003cul\u003e\n\u003cli\u003e使用 \u003ca href=\"https://gohugo.io/\"\u003eHugo\u003c/a\u003e + \u003ca href=\"https://github.com/adityatelange/hugo-PaperMod\"\u003ePaperMod\u003c/a\u003e 构建\u003c/li\u003e\n\u003cli\u003e部署在 \u003ca href=\"https://pages.cloudflare.com/\"\u003eCloudflare Pages\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e博客源码托管在 \u003ca href=\"https://github.com/162015\"\u003eGitHub\u003c/a\u003e\u003c/li\u003e\n\u003c/ul\u003e\n\u003cp\u003e联系我：hi@162015.xyz\u003c/p\u003e","title":"关于"},{"content":"欢迎来到我的新博客 这是我用 Hugo + Cloudflare Pages 搭建的博客，第一篇 Markdown 测试！\npackage main import \u0026#34;fmt\u0026#34; func main() { fmt.Println(\u0026#34;Hello, Cloudflare!\u0026#34;) } ","permalink":"https://blog.162015.xyz/posts/hello-world/","summary":"\u003ch3 id=\"欢迎来到我的新博客\"\u003e欢迎来到我的新博客\u003c/h3\u003e\n\u003cp\u003e这是我用 \u003cstrong\u003eHugo\u003c/strong\u003e + \u003cstrong\u003eCloudflare Pages\u003c/strong\u003e 搭建的博客，第一篇 Markdown 测试！\u003c/p\u003e\n\u003cdiv class=\"highlight\"\u003e\u003cpre tabindex=\"0\" class=\"chroma\"\u003e\u003ccode class=\"language-go\" data-lang=\"go\"\u003e\u003cspan class=\"line\"\u003e\u003cspan class=\"cl\"\u003e\u003cspan class=\"kn\"\u003epackage\u003c/span\u003e\u003cspan class=\"w\"\u003e \u003c/span\u003e\u003cspan class=\"nx\"\u003emain\u003c/span\u003e\u003cspan class=\"w\"\u003e\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003cspan class=\"line\"\u003e\u003cspan class=\"cl\"\u003e\u003cspan class=\"w\"\u003e\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003cspan class=\"line\"\u003e\u003cspan class=\"cl\"\u003e\u003cspan class=\"w\"\u003e\u003c/span\u003e\u003cspan class=\"kn\"\u003eimport\u003c/span\u003e\u003cspan class=\"w\"\u003e \u003c/span\u003e\u003cspan class=\"s\"\u003e\u0026#34;fmt\u0026#34;\u003c/span\u003e\u003cspan class=\"w\"\u003e\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003cspan class=\"line\"\u003e\u003cspan class=\"cl\"\u003e\u003cspan class=\"w\"\u003e\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003cspan class=\"line\"\u003e\u003cspan class=\"cl\"\u003e\u003cspan class=\"w\"\u003e\u003c/span\u003e\u003cspan class=\"kd\"\u003efunc\u003c/span\u003e\u003cspan class=\"w\"\u003e \u003c/span\u003e\u003cspan class=\"nf\"\u003emain\u003c/span\u003e\u003cspan class=\"p\"\u003e()\u003c/span\u003e\u003cspan class=\"w\"\u003e \u003c/span\u003e\u003cspan class=\"p\"\u003e{\u003c/span\u003e\u003cspan class=\"w\"\u003e\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003cspan class=\"line\"\u003e\u003cspan class=\"cl\"\u003e\u003cspan class=\"w\"\u003e    \u003c/span\u003e\u003cspan class=\"nx\"\u003efmt\u003c/span\u003e\u003cspan class=\"p\"\u003e.\u003c/span\u003e\u003cspan class=\"nf\"\u003ePrintln\u003c/span\u003e\u003cspan class=\"p\"\u003e(\u003c/span\u003e\u003cspan class=\"s\"\u003e\u0026#34;Hello, Cloudflare!\u0026#34;\u003c/span\u003e\u003cspan class=\"p\"\u003e)\u003c/span\u003e\u003cspan class=\"w\"\u003e\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003cspan class=\"line\"\u003e\u003cspan class=\"cl\"\u003e\u003cspan class=\"w\"\u003e\u003c/span\u003e\u003cspan class=\"p\"\u003e}\u003c/span\u003e\u003cspan class=\"w\"\u003e\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\u003c/div\u003e","title":"Hello World"}]