从Hexo转Hugo构建博客

发表于：

直接驱动因素

Hexo 的 npm 包依赖过多，源仓库臃肿

Hexo 基于 Node.js，每个主题、插件、甚至基础功能都可能拉取一长串 node_modules 依赖。仓库中即使通过 .gitignore 排除了 node_modules，package.json 和 package-lock.json 中记录的依赖树依然庞大，克隆和备份时负担不轻。有网友甚至因为不想让 node_modules 污染同步文件夹，直接转向了 Hugo。Hugo 则只有一个二进制文件，下载即用，没有 node_modules 这样的目录需要管理或同步。

新电脑部署时下载耗时，网络差时失败率高

Hexo 在新环境部署需要：安装 Node.js → 配置 npm（可能还要换源）→ npm install 拉取完整依赖树。依赖越多，网络不稳时失败的概率越大。网友的迁移记录中明确提到，Hexo 换环境“需重装依赖，可能有版本冲突”，而 Hugo “零依赖：单个可执行文件，跨平台即用，部署极简”。在新电脑上只需要拿到 Hugo 二进制（或一条 pacman -S hugo / brew install hugo），克隆仓库即可开始构建，没有批量下载 npm 包的环节。

构建耗时明显，写作预览体验受影响

你提到 Hexo 构建明显更耗时。实测数据也支持这一点：有用户 225 篇文章，Hexo 构建需要几十秒，而 Hugo 不到 1 秒完成。另有用户使用 Cloudflare 自动构建时，Hexo 每次约 2 分 30 秒，Hugo 降至 22 秒左右。基准测试中，Hugo 生成 10,000 页约 2.95 秒，而 Hexo 生成 1,000 页就需要约 45 秒，平均每页耗时相差一个数量级以上。构建越慢，本地预览和 CI/CD 反馈的等待感越强，Hugo 的毫秒级到秒级反馈让写作迭代明显更顺畅。

Arch Linux 滚动更新导致组件不统一，构建失败

Arch Linux 的滚动更新节奏快，Node.js 大版本升级频繁。Hexo 的插件和主题对 Node 版本敏感，一次系统更新就可能触发 ERR_REQUIRE_ESM、模块找不到或版本不匹配等报错，排查成本很高。有用户明确表示，Hexo 的依赖“经常因为版本升级出问题”，两次因 Node 版本升级导致构建失败，“排查起来非常耗时”。Hugo 是静态编译的 Go 二进制，不依赖系统 Node.js 运行时，系统包更新不会间接破坏博客构建链。在 Arch 上直接 sudo pacman -S hugo 即可，没有 Node 版本与 npm 依赖的耦合。

“依赖地狱”与长期维护焦虑

Hexo 的 npm 依赖树深、插件之间版本约束复杂。一个插件升级可能牵动一片依赖，锁文件也未必能完全避免冲突。有迁移者直言“受够了 Hexo 的各种依赖造成的未知问题”。更关键的是维护焦虑：自己魔改的主题和插件越多，越担心某次 Node 或依赖更新后博客直接“罢工”。Hugo 的依赖面极小，升级通常只是替换一个二进制文件，长期维护心智负担明显更低。

单二进制带来的可移植性与可复现性

Hugo 官方定义就是“一个没有外部依赖的单一二进制文件”。这意味着：

  • 同一版本的 Hugo 二进制在任何机器上行为一致，不会出现“换电脑就构建失败”；
  • 不需要在每台机器上复现一套 Node/npm 环境；
  • 仓库中不需要存放或同步环境依赖，源仓库体积更干净。

有网友从 P.A.R.A 管理角度出发，正是因为无法接受 node_modules 被同步工具一并搬运，才选择了 Hugo 的零依赖形态。

构建速度的量级差异

多位迁移者的实测指向同一结论：文章数量越多，Hexo 与 Hugo 的构建时间差距越明显。Hugo 基于 Go 的并发模型，万级页面秒级完成；Hexo 的 Node.js 单线程架构在文章量增长后线性变慢。对于个人博客，这意味着本地预览几乎无等待，提交后的 CI 构建也更快反馈，不必在“改一句话等半分钟”中消耗写作节奏。

主题与插件生态的取舍

需要客观说明：Hexo 在中文主题数量和中文文档丰富度上仍有优势，200+ 中文主题、大量教程对新手友好。Hugo 主题数量不少（300+），但质量参差，部分文档以英文为主。不过 Hugo 内置了大量 Hexo 需要插件才能实现的功能（如短代码、图片处理、多语言、语法高亮），减少了对第三方插件的依赖，这在长期维护上反而是一种优势。如果你已经在用较现代、维护活跃的 Hugo 主题（如 PaperMod、Blowfish），主题本身的维护负担通常低于 Hexo 上深度定制的主题。

迁移前需要知道的“代价”

Hugo 并非零成本切换，以下几点在网友经验中反复出现：

  • Front Matter 更严格：Hexo 的 Front Matter 较松散，Hugo 要求更规范，可能需要脚本或人工调整日期格式、分类/标签字段。
  • 图片组织方式不同：Hexo 常用“文章 + 同名资源文件夹”，Hugo 使用 Page Bundle（文章本身是一个目录，资源放在其中）。原样拷贝可能导致图片路径全部失效，需要重新组织或写转换逻辑。
  • 旧链接需要保留：如果原 Hexo 使用了 abbrlink 或自定义 permalink，迁移到 Hugo 后需通过 aliases 或重定向规则保留旧地址，避免外链和搜索引擎收录失效。
  • Go 模板语法有学习门槛：如果你深度定制过主题，Hugo 的模板语法需要重新适应；但如果使用现成主题、只做少量配置，门槛并不高。

Hugo-Next 主题

由于我的 Hexo 主题使用的 Next 主题 Next - Theme for Hexo ，所以切换成 Hugo 后依然想尽量保持这一主题，恰好已经有一个现成的主题 Hugo-Next ，这是导致我决定马上行动的原因。 然而在按照 hugo-theme-next 的说明

1
2
3

$ git clone --single-branch -b main https://github.com/hugo-next/hugo-theme-next.git hugo-theme-next
$ cd hugo-theme-next/exampleSite/
$ sh startup.sh

操作后，发现并不能顺利启动。主要原因是目录hugo-theme-next目录中有一个案例exampleSite, 但是在exampleSite中缺失themes, 这个结构上的混乱导致无法构建成功。修复方法是：

  • 将exampleSite移动到hugo-theme-next外，单独构成一个新的目录exampleSite
  • 在exampleSite下新建目录themes
  • 将移除hugo-theme-next的目录移动到exampleSite/themes下
  • 不要使用startup.sh启动，因为这个脚本只是提供了一个Next的图标，并且测试时无法运行。直接使用hugo sever -D启动预览即可成功。

部署到Github

根据文章 使用静态网站生成器与GitHub-Pages部署个人博客 完成 GitHub-Pages 的设置。同时，与 Hexo 的发布命令 hexo d不同， Hugo 没有发布命令，使用hugo构建成功的 Html 文件在 public 目录下，于是直接将 public 中的html 文件上传到你的 Pages 页 https://github.com/yourname.githb.io 即可完成部署。