Hugo 博客迁移实录：从 0.111.3 到 0.164.0

Sat, 18 Jul 2026 00:00:00 +0000

我的旧博客基于 Hugo 0.111.3 + hugo-coder 主题运行了三年多，最近升级到 Hugo 0.164.0 并换用了 PaperMod 主题。整个过程比预想的顺利，但还是踩了几个坑，记录一下供有类似需求的朋友参考。

迁移背景

两个版本隔了约 50 个 minor 版本，配置格式从 TOML 切换到 YAML，主题也完全不同。迁移的核心工作就是三个：内容搬迁、配置映射、兼容性处理。

这一步最简单——直接把 content/ 目录下的所有 markdown 文件复制过去就行。

cp -r personal-blog/content/* NormanBlog/content/

我的旧博客有 90+ 篇文章和 3 个独立页面（About、Projects、List），frontmatter 都是标准的 Hugo 格式，不需要任何修改就能被新版本识别。

静态资源同理：

cp -r personal-blog/static/* NormanBlog/static/

favicon、avatar、site.webmanifest 等直接搬过去即可。

这才是迁移的重头戏。两个主题的参数体系完全不同，需要逐一对照映射。

# hugo.yaml (PaperMod)
baseURL: https://wangyu.link/
locale: en  # Hugo 0.158+ 废弃了 languageCode
title: Norman's Blog
theme: ["PaperMod"]
paginate: 20

旧配置中的 languagecode = "en" 在 Hugo 0.158.0 之后被废弃了，需要改成 locale: en。如果继续用 languageCode，构建不会失败，但会一直弹出 deprecation 警告。