Hexo博客迁移到Hugo

本博客使用Hexo已经7年了。博文和内容增多后，hexo的生成速度越来越难以满足需求啦。我的个人博客迁移到Hugo近一年了，生成的速度飞快，也没有遇到什么坑，是时候迁移了。~~顺便还能水一篇文章~~

前期准备

安装Hugo

我打算使用的主题Stack需要使用到Hugo的扩展版hugo-extended，如果你的主题没有额外的要求，按照普通版即可

Before you start, make sure you have installed Hugo extended version. For more information, see Hugo’s documentation.
This theme uses SCSS and TypeScript, that’s why Hugo extended version is required

1

choco install hugo-extended

新建网站

1
2


hugo new site-example
cd site-example

安装主题

我比较old-fashion，喜欢用sub module

1

git submodule add https://github.com/CaiJimmy/hugo-theme-stack/themes/hugo-theme-stack

基于hugo mod的安装流程请参考文档

修改site-config

我的hexo站点设置中，文章的URI加上了yyyy/MM/dd的前缀。这里调整permalinks的规则，保证兼容性

1
2
3


permalinks:
    post: "/:year/:month/:day/:slug/"
    page: /:slug/

开启$\LaTeX$处理

1
2
3


    article:
        math: true
        ...

迁移

迁移内容

Hugo支持多种front matter的格式，如YAML,TOML和JSON。出乎我预想的是，其区分格式的依据是front matter分隔符，这与Hexo不太一致。

The front matter at the top of each content file is metadata that:

Describes the content

Augments the content

Establishes relationships with other content

Controls the published structure of your site

Determines template selection

Provide front matter using a serialization format, one of JSON, TOML, or YAML. Hugo determines the front matter format by examining the delimiters that separate the front matter from the page content.

此外，页面的permalink需要在front-matter的slug中显式指定；对于内容与本地资源的命名和存放路径也与hexo不太一样。

我迁移个人博客时做了一个迁移脚本，用于处理这些差异。

原hexo中的自定义页面比较少，我自己手工迁移了。理论上脚本对post和page均有效，欢迎你尝试。如果有问题欢迎提出BUG。

开始预览

感受一下闪电般的速度

1

hugo serve

疑难问题处理

front-matter处理

hexo对front-matter的格式要求比较松散，在数组的地方填入字符串也无伤大雅。但是，hugo对格式的要求十分严格，一言不合死给你看：

1

render: failed to render pages: render of "page" failed: "C:\Users\test-user\Documents\GitHub\site-example\themes\hugo-theme-stack\layouts\_default\baseof.html:4:12": execute of template failed at <partial "head/head.html" .>: error calling partial: "C:\Users\test-user\Documents\GitHub\site-example\themes\hugo-theme-stack\layouts\partials\head\head.html:15:4": execute of template failed at <partial "head/opengraph/include.html" .>: "C:\Users\test-user\Documents\GitHub\site-example\themes\hugo-theme-stack\layouts\partials\head\opengraph\include.html:1:3": execute of template failed at <partial "head/opengraph/provider/base" .>: "C:\Users\test-user\Documents\GitHub\site-example\themes\hugo-theme-stack\layouts\partials\head\opengraph\provider\base.html:22:21": execute of template failed at <.Params.tags>: range can’t iterate over XYZ

更为致命的是，这里只告诉你字段(即tags)，但不能定位到有问题的那些文章。这就让问题的排查变得十分困难，可以说这里整个迁移中最耗时的地方了。

我自己的经验是，这里只能采用一对一处理：

上面的报错信息告诉我们出错的是tag是XYZ的文章
全局搜索找出所有的文章，只留下一篇
修改文章的tag，使其符合front-matter规定的格式
对同类型文章处理。

上文中的报错，需要把tags: 'XYZ'改为tags: ['XYZ']。

同站引用处理

hexo的博文中我使用了相对路径做同站文章的引用，例如半监督学习一文中，我使用了下面的方式引用从分类到对率回归再到到神经网络

1

[1]:../../../07/04/from-logistic-regression-to-neural-network/

这里使用hugo提供ref shortcode，可以确保permlink永远保持最新。

1

[1]:{{< ref "from-logistic-regression-to-neural-network.md" >}}

~~$\LaTeX$的hyperref既视感~~

资源处理

Hugo中，文章(index.md)与资源(resource.png)处在同一个目录(content/post/article)下。因此，原先采用相对路径引用(![test graph][./resource.png])的资源最好改成直接路径(![test graph][resource.png])。

主题Stack中展示图片时会显示caption，如果以前偷懒了最好补一下;-)

部署

调试CI/CD的yml过于麻烦，我同样采用old-fashion的hugo-deployer-git：

1
2
3


conda create -n hugo python=3.9
conda activate hugo
pip3 install hugo-deployer-git

填好config.toml

1
2
3
4


[hugo-deployer-git]
    # required
    repo = "https://github.com/Verrickt/verrickt.github.io.git"
    branch =  "hugo"

执行

1

> hugo-deployer-git

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


[master 4a4610a] :robot:  2025-08-22 09:20:33 PM
 9 files changed, 12 insertions(+), 12 deletions(-)
Enumerating objects: 39, done.
Counting objects: 100% (39/39), done.
Delta compression using up to 16 threads
Compressing objects: 100% (17/17), done.
Writing objects: 100% (20/20), 1.66 KiB | 1.66 MiB/s, done.
Total 20 (delta 11), reused 0 (delta 0), pack-reused 0
remote: Resolving deltas: 100% (11/11), completed with 11 local objects.
To https://github.com/Verrickt/verrickt.github.io.git
   adad295..4a4610a  HEAD -> hugo
branch 'master' set up to track 'https://github.com/Verrickt/verrickt.github.io.git/hugo'.

大功告成！