Hugo 搭建踩坑记录（2026-09-06）

Sun, 06 Sep 2026 08:30:00 +0800

今天第一次搭 Hugo + PaperMod + Cloudflare Pages，照着网上笔记抄，结果踩了 4 个坑。记录下来防自己再踩。

坑 1：`hugo.toml` 里的连字符不是普通 `-`

我抄的笔记里写的是 languageCode = "zh‑CN"，看着像普通连字符，实际上是 U+2011 non-breaking hyphen。TOML 解析没问题，但语言码识别不对。

解决：全部用 ASCII 普通连字符 "zh-CN"。

类似的，baseURL = "https://xxx.pages.dev" 里的 xxx 占位符没换成本地预览也能跑，但部署后所有相对路径都会指向 xxx.pages.dev，必须换成 Cloudflare 分配的真实地址。

我的版本是 0.165，弃用警告：

WARN  deprecated: project config key languageCode was deprecated in Hugo v0.158.0

解决：用新的 [languages.zh] 配置块：

defaultContentLanguage = "zh"

[languages.zh]
  languageName = "中文"
  weight = 1

⚠️ 但单语言博客继续用 languageCode 也行（只是有警告），不必为了消除警告折腾。PaperMod 主题本身也还在用旧的 .Language.LanguageDirection 等，新警告都是 cosmetic 的。

Sun, 06 Sep 2026 07:30:00 +0800

这里写你的记录，普通 Markdown 全部支持：

def hello():
    print("Hello, Hugo + PaperMod!")

行内公式：$E = mc^2$

块级公式：

$$ \int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi} $$

自我记录模式：可以随手写，不追求排版，重点是把知识沉淀下来。

写完后 hugo server -D 本地预览，确认 OK 再 git push 推到 Cloudflare 自动部署。