前言

最近整理博客依赖, 发现本地还是 hexo 7.3.0, 而官方已经发布到 8.1.0 了。中间隔着 8.0.0 这个大版本, 时隔一年多(2024-07 → 2025-09), 不少东西都变了。

这篇记录一下升级过程中踩到的坑, 供同样在使用 Hexo 的朋友参考。

先说结论: 升级本身不难, 难的是 Node 版本和插件生态的错配。

版本现状对照

在动手之前, 先看清楚自己站在哪里:

组件	我的版本	当前最新	发布时间
Hexo	7.3.0	8.1.0	7.3.0 是 2024-07, 8.0.0 是 2025-09
hexo-theme-butterfly	5.2.2	5.7.0	—
Node.js	22.22.2 LTS	建议 22/24 LTS	—

查版本和发布日期:

# 查看本地 hexo 版本
npx hexo version

# 查看主题版本
cat themes/butterfly/package.json | grep version

# 查看 node 版本
node -v

也可以直接看官方 hexo.io 首页的 Releases 列表, 版本发布时间写得很清楚。

第一个坑: Node 版本不达标

官方 breaking change

Hexo 8.0.0 的 release note 里, Breaking Changes 一栏只有两条, 但都很硬:

chore: drop Node.js 16
chore: drop Node.js 18

也就是说, Hexo 8 要求 Node.js 20.19.0 或更高版本。

如果你的环境还是 Node 16 或 18, 升级 Hexo 之后大概率会直接报错, 或者在装依赖的时候就一堆 warning。

检查自己的 Node 版本

1 2	node -v npm -v

如果版本号开头是 v16. 或 v18., 那就必须先升级 Node, 再动 Hexo。

我这里用的是 Node 22.22.2 LTS, 直接满足要求, 所以没踩这一步。如果你恰好还在 18 上, 请务必先升 Node, 不要直接升 Hexo, 否则排查方向会完全跑偏。

第二个坑: ERR_REQUIRE_ESM

这是我看到的最高频的一个报错:

1
2
3

npm install
# 或者 hexo g 时
Error [ERR_REQUIRE_ESM]: require() of ES Module ... from ... not supported

根因分析

这不是 Hexo 本身的问题, 而是一个依赖版本错配问题。

Hexo 8 把很多底层依赖都往上提了一轮, 比如 hexo-util 从 3 提到 4。而一些老的第三方插件并没有跟着更新, 它们内部还依赖着旧版的 strip-ansi。

关键在于 strip-ansi 这个包的版本差异:

strip-ansi@6.x —— CommonJS, 可以被 require()
strip-ansi@7.x —— 改成了 ESM, require() 会直接报错

新版 Hexo 依赖链里会带进 strip-ansi@7, 而老插件内部还在用 require() 加载它, 于是就撞上了。

解决办法

思路是在你的项目里强制降级这个传递依赖, 让老插件能找到它认识的格式:

1	npm install strip-ansi@6.0.1 --save-exact

这条命令会在你的项目根目录放一个”旧版零件”, 所有插件都能拿到, 从而避开 ESM 冲突。

验证

1 2	hexo clean hexo s

如果 hexo s 能正常起服务, 说明问题解决了。

第三个坑: 别用 npm update

这是习惯问题, 但影响很大。

以前升级 Hexo 我习惯用 npm update, 这次没有继续这么做。原因是 npm update 会把范围内所有依赖都往最新拉, 一旦某个中间包出了不兼容的版本, 排查起来非常痛苦。

更稳妥的做法是在 package.json 里锁定关键依赖的主版本:

{
  "engines": {
    "node": ">=22 <25"
  },
  "dependencies": {
    "hexo": "8.1.0",
    "hexo-theme-butterfly": "5.7.0"
  }
}

这样以后删掉 node_modules 重新安装, 得到的是同一套环境, 不会因为”今天装的和上次装的不是一个东西”而困惑。

顺便说一句, engines 这个字段很值得加, 它能在安装阶段就提醒你 Node 版本对不对。

升级前的准备: 两层回退

升级这种事, 备份不是可选项。

我给自己的博客目录建了两层回退:

第一层: Git 基线

git init
git add -A
git commit -m "baseline: pre-Hexo-8"
git tag pre-hexo8
git switch -c upgrade/hexo-8

好处是任何配置和源码问题都能用 Git 直接定位和回滚。

第二层: 完整压缩包

博客目录里除了 source/, 还有 node_modules/、生成的 public/、部署用的 .deploy_git/, 以及主题目录里的 Git 历史。这些东西 Git 不好管, 建议打一个完整压缩包。

# 以 Linux 为例
tar -czf hexo-backup-$(date +%Y%m%d).tar.gz --exclude=node_modules .

# Windows PowerShell
Compress-Archive -Path . -DestinationPath hexo-backup-20261021.zip

打完包之后, 建议算一下 SHA-256 校验值, 确认压缩包真的能解开, 而不是坏在那儿了。

完整操作流程

把上面的步骤串起来:

# 1. 确认当前版本
npx hexo version
node -v

# 2. 备份(别跳过这步)
# 打压缩包 + 算校验值

# 3. Git 基线
git add -A && git commit -m "baseline: pre-Hexo-8"

# 4. 切换分支, 开始升级
git switch -c upgrade/hexo-8

# 5. 升级 Hexo
npm install hexo@8.1.0 --save

# 6. 如果报 ERR_REQUIRE_ESM, 强制降级
npm install strip-ansi@6.0.1 --save-exact

# 7. 验证
hexo clean
hexo s