HEXO 6.3 & NEXT 8.18.2 版本升级记录

发表于 更新于 阅读次数： 本文字数： 842 阅读时长 ≈ 3 分钟

原本 HEXO v5.4.2 基于 node v12 版本，但最近个别组件出现安全告警要求强制升级，但新版本的组件依赖 node v14 版本，只好再次升级。
version

其中一个开发设备是古老的 Mac 一体机，通过 node 官网下载 v18 的 pkg 安装包，运行异常退出，核查原因是操作系统版本是 High Sierra 10.13（最后一个支持32位App的版本，告别了僵尸大战！），被迫升级到 Catalina 10.15，经过好几番折腾，最后完成情况如下：

node：最新版本 v20，LTS 版本 v18
npm：9.8.1
Hexo：6.3
Next：8.18.2

package.json 配置信息

删除依赖库目录 node_modules/ ，修改安装配置文件，然后重新npm install

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
{
  "name": "hexo-site",
  "version": "0.0.0",
  "private": true,
  "scripts": {
    "build": "hexo generate",
    "clean": "hexo clean",
    "deploy": "hexo deploy",
    "server": "hexo server"
  },
  "hexo": {
    "version": "6.3.0"
  },
  "dependencies": {
    "@next-theme/plugins": "^8.18.2",           # Next主题的对应插件
    "hexo": "^6.3.0",                           # 主服务
    "hexo-auto-excerpt": "^1.1.0",              # 首页显示文章摘要，而非全文
    "hexo-deployer-git": "^4.0.0",              # git 远程发布
    "hexo-filter-mermaid-diagrams": "^1.0.5",   # mermaid 流程图的插件
    "hexo-generator-archive": "^2.0.0",         # 生成归档信息
    "hexo-generator-category": "^2.0.0",        # 生成分类信息
    "hexo-generator-index": "^3.0.0",           # 生成目录信息
    "hexo-generator-searchdb": "^1.4.1",        # 生成本地搜索数据库
    "hexo-generator-tag": "^2.0.0",             # 生成标记信息
    "hexo-renderer-ejs": "^2.0.0",              # EJS 渲染引擎，支持 v3 版本
    "hexo-renderer-marked": "^6.1.1",           # Markdown 渲染引擎
    "hexo-renderer-stylus": "^3.0.0",           # Stylus CSS 解析引擎
    "hexo-server": "^3.0.0",                    # 本地 Web 服务器
    "hexo-theme-next": "^8.18.2",               # Next 主题
    "hexo-word-counter": "0.1.0"                # 字数统计的插件
  }
}

_config.yml 配置信息

注意需修改 hexo 的主配置文件！然后，根据需要相应调整 Next 的配置文件。

1
2
3
4
5
post_asset_folder: true
marked:
  prependRoot: true
  postAsset: true
  dompurify: false  # 默认启用HTML标签净化，将导致markdown代码渲染失败

更新说明

出于 HTML 安全考虑，新版本的hexo-renderer-marked 嵌入了DOMPurify，但经常造成渲染异常，已建议采用新的插件 hexo-renderer-markdown-it。

hexo-auto-excerpt插件通常用于显示文章摘要，已改为独立安装插件，而非进行配置；但由于 HTML 难以准确截断，推荐采用<!-- more -->标签在文章内部进行显式截断。
注意！默认版本 1.1.0 正常，但强制升级到最新 1.1.2 可能造成首页渲染错位

Hexo 默认安装了 hexo-renderer-marked 和 hexo-renderer-ejs，因此你不仅可以用 Markdown 写作，你还可以用 EJS 写作。如果你安装了 hexo-renderer-pug，你甚至可以用 Pug 模板语言书写文章。只需要将文章的扩展名从 md 改成 ejs。

早期 Next 主题的版本库位于：theme-next/hexo-theme-next，由于开发团队的内部矛盾而长期无法更新…于是部分开发者又搞了一个新版本：next-theme/hexo-theme-next，这就是 5.x 版本升级到 8.x 版本的重大变换，主要改造点：

  • 将配置文件移动到最外层，使用_config.next.yml，目的是后续的主题更新只需git pull，不需要担心配置文件冲突或者丢失的问题
  • 把库文件独立出来：@next-theme/plugins；该插件需要独立安装，且版本号务必相同
  • 模板格式从 swig 调整为 njk
  • 保留 git 安装方式，但也可以支持 npm

参考文献