Hexo 版本更新与技术债务

首页发现

逸思杂陈

家用网络 vlan 单线复用 Linux 平台 intel UHD 6xx 核显 openvino 探索 UI 区域检测的 vibe coding 复盘 mitmproxy 使用 esim 使用相关阻止 bilibili 网页自动关注配置 Linux 作为主力操作系统在 Linux 虚拟机中使用 PyAutoGUI 做自动化语言的力量联想笔记本 BIOS 跳过检测强制降级 redroid “设备未获得play保护机制认证” 问题在 iOS 上访问安卓应用在 VSCode 中用 Rust 刷LeetCode 跨域的那些事 HomeBrew 与无 root 权限 Linux 环境包管理给 macOS 词典增加生词本功能关闭子进程打开的文件描述符容器内进程优雅退出 Python 循环变量泄露与延迟绑定 bash 语法备忘 MySQL 自定义数据库路径

Hexo 版本更新与技术债务

Jay.Run · 2026-01-02 · via 逸思杂陈

昨天花了些时间将 Hexo + next 的博客版本更新了下，发现不少问题。
博客已经很多年了，一直用的是最开始的Hexo版本，nodejs 也是 v12，next 主题也是早年源码安装的，还在上面做了修改。
也是早就明白需要更新了，但是觉得麻烦，就一直没动，最后变得相当麻烦。

依赖更新

首先是版本升级，先将 nodejs 切换到最新 lts（v22）。
再尝试使用npm将 package.json 中的库自动更新，但由于版本差距太大以及很多库不维护了，更新不了。

最后只能使用 hexo init 新建个博客项目，将里面的依赖项复制到老博客里，删除对应的老依赖。
剩下的依赖，大部分是安装的插件，只能一个个搜索用途，看看有没有替代或者还要不要用。
package.json 中的其他参数，参考最新的配置文件，将无用（过时）的设置项删除。

使用 npm 安装 next 主题，将原 themes/next 中的配置文件复制到 _config.next.yml。
对比 hexo 和 next 官方 _config 文件，相应修改 _config.yml 和 _config.next.yml。
删除 themes 中重复的主题目录。

使用 npm install 安装依赖，保证能够正常生成博客。

删除 node_modules，改用 pnpm 管理依赖，更轻量快速。
使用 pnpm 时可能会报错，如某个库的 index.node 找不到，是因为 pnpm 默认不执行库的 post install 脚本。
需要将这些库添加到 pnpm.onlyBuiltDependencies 中。

"pnpm": {
  "onlyBuiltDependencies": [
    "hexo-word-counter",
    "hexo-util"
  ]
 }

ps:

总体来说 pnpm 还是存在一些兼容性问题，但大部分都不是 pnpm 本身的问题，基本上都是库的影子依赖。
大模型在这种疑难杂症上帮助很大

额外设置

hexo

修改 scaffolds 文章模板文件
老版本 hexo 的 scaffolds/page.md 等文件格式与新版不同，会导致一些工具不能识别 front-matter, 需要更新。

老版本 front-matter 前面少了开头的 ---，导致 vscode 的 hexo-util 插件不能识别 tag 等信息，调试了很久。


title: {{ title }}
date: {{ date }}
---


---
title: {{ title }}
date: {{ date }}
---

自定义样式和脚本，之前是通过之间修改主题源码实现，现在使用 custom_file_path 注入自定义内容。
需要修改 _config.next.yml 文件

custom_file_path:
  head: source/_data/head.njk
  bodyEnd: source/_data/body-end.njk
  style: source/_data/styles.styl

自定义样式

next 主题的 Muse scheme 整体比较符合我的口味，但部分样式还需要微调。

source/_data/styles.styl


// 自动给文章的 toc 和正文标题编号, 不对首页编号
body {counter-reset: h1}
.post-block .post-body h2 {counter-reset: h2}
.post-block .post-body h3 {counter-reset: h3}
.post-block .post-body h4 {counter-reset: h4}
.post-block .post-body h5 {counter-reset: h5}
.post-block .post-body h6 {counter-reset: h6}

.post-block .post-body h2:before {
  counter-increment: h1;
  content: counter(h1) ". "
}
.post-block .post-body h3:before {
  counter-increment: h2;
  content: counter(h1) "." counter(h2) " "
}
.post-block .post-body h4:before {
  counter-increment: h3;
  content: counter(h1) "." counter(h2) "." counter(h3) " "
}
.post-block .post-body h5:before {
  counter-increment: h4;
  content: counter(h1) "." counter(h2) "." counter(h3) "." counter(h4) " "
}
.post-block .post-body h6:before {
  counter-increment: h5;
  content: counter(h1) "." counter(h2) "." counter(h3) "." counter(h4) "." counter(h5) " "
}
.post-block .post-body h1.nocount:before,
.post-block.post .post-body h2.nocount:before,
.post-block.post .post-body h3.nocount:before,
.post-block.post .post-body h4.nocount:before,
.post-block.post .post-body h5.nocount:before,
.post-block.post .post-body h6.nocount:before {
  content: "";
  counter-increment: none
}

// 隐藏文章 toc 中文章目录 tab 中的友链信息，站点概览中的保留
.sidebar .sidebar-toc-active + .sidebar-blogroll {
    display: none
}

只在文章页显示侧边栏

next 主题的侧边栏逻辑有点问题，就算设置 sidebar.display 为 post，当从文章跳到其他页面时，侧边栏并不会自动关闭，所以只能通过脚本来绕过。

source/_data/body-end.njk

<script>
  document.addEventListener('pjax:success', () => {
    if (CONFIG.sidebar.display !== 'remove') {
      const hasTOC = document.querySelector('.post-toc:not(.placeholder-toc)');

      
      if (!hasTOC && document.body.classList.contains('sidebar-active')) {
        window.dispatchEvent(new Event('sidebar:hide'));
      }
    }
  });
</script>

自定义重定向

hexo 的文章不支持多个入口，比如我想要分类中英文都可以访问，默认情况是做不到的。

在设置了 category_map 的情况下，hexo 只会生成 programming 等英文链接，无法同时保留中文url作为入口。

category_map:
  编程: programming
  随笔: writing
  阅读: reading
  工作生活: life

所以最终通过在 404 页面添加自定义的 js 实现重定向逻辑。

source/_data/head.njk

{% if page.title === '404 Page Not Found' or page.type === '404' or page.layout === '404' %}
<script>
(function() {
  
  var categoryMap = {{ config.category_map | dump | safe }};
  var currentPath = decodeURIComponent(window.location.pathname);

  
  for (var key in categoryMap) {
    if (currentPath.includes(key)) {
      var targetCategory = categoryMap[key];
      var targetPath = currentPath.replace(key, targetCategory);

      
      if (currentPath !== targetPath) {
        window.location.replace(targetPath);
        return;
      }
    }
  }
})();
</script>
{% endif %}

更换 gitalk 为 utterances

原先一直使用 gitalk 作为文章的评论系统。
gitalk 每个新文章都需要作者登陆触发新建评论 issue，不太方便，所以现在换成 utterances。

utterances 评论插件 next 主题已内置，修改 _config.next.yml 可以开启。


utterances:
  enable: true
  repo: ruanimal/ruanimal.github.io 
  
  issue_term: title

还需要在 github pages 仓库安装 utterances 应用。

自定义的域名可能不被 utterances 支持，无法登陆跳转
需要新建 source/utterances.json

{
  "origins": [
    "https://blog.ponder.work",
    "https://ruanimal.github.io"
  ]
}

如果你和我一样，博客有多个域名，副域名登陆跳转会失效，可以通过注入js修正
utterances 的登陆跳转是根据 canonical link，我们只要让它和当前url保持一致就行了

在 source/_data/head.njk 文件添加以下内容

<script>
(function() {
  var canonical = document.querySelector('head > link[rel="canonical"]');
  if (canonical && canonical.href) {
    try {
      var oldUrl = new URL(canonical.href);
      canonical.href = window.location.origin + oldUrl.pathname + oldUrl.search + oldUrl.hash;
    } catch (e) {
      console.warn('Failed to update canonical link:', e);
    }
  }
})();
</script>

更换编辑器

之前一直是用 mac 平台是 mweb 作为 hexo 的文章编辑器，实话说也非常好用。
但是我把主力操作系统换成 linux 之后，linux 上一直没找到与 mweb 相当的应用。
最终经过一番折腾，最终使用 vscode + Hexo Utils 插件作为平替。
同时对该插件进行来二开，最终体验算是追平了 mweb。

感受

所谓技术债务，项目正常迭代的过程中是不断积累的，如果平时不跟进解决，最终在某个阶段就会爆炸，造成巨大影响。

平时迭代时，如果时间安排的过紧，我们就会倾向于采取保守的决策（能跑就不要动），最终不可避免的技术债务堆积。

当然，生活中其实也是这样吧，很多不紧急的问题，一直拖着，最终大概率也会无可挽回。

此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。原文来自 — 版权归原作者所有。

推荐订阅源

逸思杂陈

依赖更新

额外设置

hexo

next

自定义样式

只在文章页显示侧边栏

自定义重定向

更换 gitalk 为 utterances

更换编辑器

感受