深夜两点把博客从 Hexo 迁到 Hugo

事情要从一个让我抓狂的下午说起。

我按惯例写完一篇随笔,敲下 hexo s 想预览一下,然后端起杯子去倒水。等水倒好、喝了两口回来,终端还在那儿吭哧吭哧编译。一篇 markdown 而已啊大哥,至于吗?

这已经不是第一次了。每次改一个字,就要等它把整个站重新跑一遍。文章一多起来,那个编译时间真的够我看完一个短视频。头发又少了几根的根本原因,可能不是写代码,是等编译等掉的。

忍了一阵子,终于在一个深夜破防了——干脆迁了吧,听说 Hugo 编译快得离谱,而且也是 Go 写的,我栈里好歹有点 Go,亲切。

然后就开始了半夜两点的折腾。

其实选 Hugo 没什么纠结的。原因就两条:

Hexo 那套 Node 依赖每次换机器都要 npm install 半天,版本飘了还能给你爆一堆 deprecation warning,真的够了。

本来计划很美好,直接照着官方推荐用 Hugo Module 把主题以模块方式拉进来,显得很现代、很优雅。

结果 hugo mod 一通操作,主题死活加载不出来。页面要么空模板,要么报一堆找不到 shortcode 的错。

我盯着日志看了半天:

1
2

WARN .File.Path 被忽略;主题可能需要更新 .File.UniqueID
ERROR ... 找不到某 shortcode

后来翻了半天 issue 才悟了——Hugo Module 是基于 Git 的,它走的是模块仓库的默认分支。 我用来当主题 fork 的那个仓库,默认分支被人改过(或者我 clone 的时候 branch 没拉对),加载的根本不是我以为的那份代码。hugo mod 拿到的 commit 对不上号,自然一堆东西缺失。

折腾到一个点的时候真想骂人:我明明什么都没改,它就是不认。

想明白之后我果断换思路。Hugo Module 太“新潮”,对 Git 分支和仓库结构有强假设,稍微不对就给你整玄学错误。我这种只是想稳稳挂个主题的人,没必要陪它玩这套。

换回老古董但老好使的方案:Git Submodule。

1
2

git submodule add https://github.com/xxx/fixit.git themes/FixIt
git submodule update --init --recursive

虽然 submodule 被 IT 圈吐槽无数,什么“换机器忘记 init”、“detached HEAD 看不懂”——但它就一点好:你拉下来的就是那个 commit,是什么就是什么,不会因为远端分支动了给你变戏法。

对我这种半夜两点脑子发木的人,确定性比优雅重要一万倍。

挂上 submodule,主题稳稳加载,第一个大坑填上了。 当然也有可能是我自己的问题吧

真正让我对 Claude Code 真香的事来了。

Hugo 的配置和 Hexo 那套 _config.yml 完全不是一个画风。Hugo 用 TOML,还分 hugo.toml、params、languages、menus 一堆,加上 FixIt 主题那一长串自定义参数,我看着几百行的配置头皮发麻。

全手改?两点钟的我做不到。

于是我开了 Claude Code,让它帮我对比着 docs 把配置一项一项撸顺。说真的,这种“半 lain 重复、又需要点判断力”的活儿,交给 AI 真的比自己熬夜撑着快太多。

我大概的流程是:

省心。本来要熬到天亮的活儿,半小时基本搭起来了。当然中间它也犯傻过,把 docs 里别人站点的 token 当模板往我这儿填,被我一眼揪出来回滚了——AI 辅助归辅助,该 review 的地方一眼都不能省,尤其是凭据类的东西。

全部收拾完,敲下:

1

hugo server -D

回车到页面出来,大概……一秒多点?当时我甚至愣了一下,以为没编出来。翻终端看日志,确实是全量构建完了,就这么快。

我又试着加了个字保存,几乎瞬间热更新刷出来。和之前 Hexo 那个“改一个字去泡杯咖啡”的体验,完全两个世界。

这一刻突然觉得半夜两点没白熬。

这次迁移下来几个血泪教训:

现在我是在 Hugo 上敲的这篇,边写边预览。