Hugo 部署 Cloudflare 的踩坑记录

最近把 Hugo 博客部署到 Cloudflare Pages，看着简单，结果踩了一堆坑。记录一下，给后面的人省点时间。

坑一：主题文件别手写

一开始图省事，手动推了个简化版 PaperMod 主题到仓库。结果功能不全、CSS 缺失、搜索用不了。

正确做法： 构建时直接拉官方主题，别自己维护一份。

git clone --depth 1 https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod

坑二：HUGO_VERSION 必须和主题匹配

PaperMod 要求 Hugo >= 0.146.0，但 Cloudflare 默认可能是老版本。

解决： 在 Cloudflare Pages 环境变量里指定版本。

HUGO_VERSION = 0.146.0

坑三：TOML 语法别用 YAML 的写法

minify: 这种冒号写法是 YAML 的，TOML 要用 [minify] 表头。Cloudflare 用的是标准 TOML 解析器，一个字符错就整个构建失败。

[minify]
disableXML = true

坑四：代码块要标注语言

Markdown 代码块如果不标注语言，Hugo 可能渲染异常。目录结构这种用 text：

project/
|-- file1.py
+-- file2.py

坑五：域名要加到 Pages 白名单

光在 DNS 配 CNAME 不够，Pages 项目本身也要把域名加进去，否则不响应请求。

坑六：构建日志看不到

Cloudflare Pages 的构建日志 API 不开放，只能网页上看。构建失败时，把日志贴出来就能定位。

总结

其实核心就一句话：跟官方 exampleSite 对齐，别自己发挥。 主题、版本、配置、域名，全都按官方来，基本不会出问题。

本文由 AI 辅助生成。