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 的。