慕雪的小助手正在绞尽脑汁···
慕雪小助手的总结
DeepSeek & LongCat

太久没有升级过hexo了，现在用的4.9.0版本主题已经是2023年10月的老东西了，准确来说是在我配置好了butterfly主题之后基本上就没有动过。

github.com/jerryc127/hexo-theme-butterfly/releases/tag/5.3.5

本次打算升级5.3.5版本，是3月4日发布的。目前mac上使用的npm和node版本号如下

1
2
3
4
5
❯ npm --version
10.8.2

❯ node --version
v20.18.0

1. hexo升级

首先需要升级hexo 7版本，现在使用的是hexo 6.3.0版本。升级hexo步骤如下，参考：1px.run/hexo/upgrade/

首先是列出过期的包

1
2
3
4
5
6
7
8
9
10
11
12
13
14
❯ npm outdated
Package                  Current  Wanted  Latest  Location                              Depended by
hexo                       6.3.0   6.3.0   7.3.0  node_modules/hexo                     blog
hexo-deployer-git          3.0.0   3.0.0   4.0.0  node_modules/hexo-deployer-git        blog
hexo-filter-mathjax        0.8.1   0.8.1   0.9.0  node_modules/hexo-filter-mathjax      blog
hexo-generator-archive     1.0.0   1.0.0   2.0.0  node_modules/hexo-generator-archive   blog
hexo-generator-category    1.0.0   1.0.0   2.0.0  node_modules/hexo-generator-category  blog
hexo-generator-index       2.0.0   2.0.0   4.0.0  node_modules/hexo-generator-index     blog
hexo-generator-searchdb    1.4.1   1.5.0   1.5.0  node_modules/hexo-generator-searchdb  blog
hexo-generator-tag         1.0.0   1.0.0   2.0.0  node_modules/hexo-generator-tag       blog
hexo-renderer-marked       5.0.0   5.0.0   7.0.1  node_modules/hexo-renderer-marked     blog
hexo-renderer-stylus       2.1.0   2.1.0   3.0.1  node_modules/hexo-renderer-stylus     blog
hexo-theme-landscape       0.0.3   0.0.3   1.1.0  node_modules/hexo-theme-landscape     blog
uuid                       8.3.2   8.3.2  11.1.0  node_modules/uuid                     blog

然后根据这里的版本号修改package.json文件

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
33
34
35
36
37
38
39
40
{
  "name": "hexo-site",
  "version": "1.0.0",
  "private": true,
  "scripts": {
    "build": "hexo generate",
    "clean": "hexo clean",
    "deploy": "hexo deploy",
    "server": "hexo server"
  },
  "hexo": {
    "version": "7.3.0"
  },
  "dependencies": {
    "hexo": "^7.3.0",
    "hexo-abbrlink": "^2.2.1",
    "hexo-baidu-url-submit": "^0.0.6",
    "hexo-blog-encrypt": "^3.1.6",
    "hexo-deployer-git": "^4.0.0",
    "hexo-filter-mathjax": "^0.9.0",
    "hexo-generator-archive": "^2.0.0",
    "hexo-generator-baidu-sitemap": "^0.1.9",
    "hexo-generator-category": "^2.0.0",
    "hexo-generator-feed": "^3.0.0",
    "hexo-generator-index": "^4.0.0",
    "hexo-generator-searchdb": "^1.5.0",
    "hexo-generator-sitemap": "^3.0.1",
    "hexo-generator-tag": "^2.0.0",
    "hexo-hide-posts": "^0.4.3",
    "hexo-neat": "^1.0.9",
    "hexo-renderer-ejs": "^2.0.0",
    "hexo-renderer-marked": "^7.0.1",
    "hexo-renderer-pug": "^3.0.0",
    "hexo-renderer-stylus": "^3.0.1",
    "hexo-server": "^3.0.0",
    "hexo-theme-landscape": "^1.1.0",
    "hexo-wordcount": "^6.0.1",
    "uuid": "^11.1.0"
  }
}

修改完毕后，重新安装新的包

1
npm install --save

使用hexo version确认包更新成功。

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
33
34
35
36
37
38
39
40
❯ hexo version
INFO  Validating config
INFO  
  ===================================================================
      #####  #    # ##### ##### ###### #####  ###### #      #   #
      #    # #    #   #     #   #      #    # #      #       # #
      #####  #    #   #     #   #####  #    # #####  #        #
      #    # #    #   #     #   #      #####  #      #        #
      #    # #    #   #     #   #      #   #  #      #        #
      #####   ####    #     #   ###### #    # #      ######   #
                            4.9.0
  ===================================================================
hexo: 7.3.0
hexo-cli: 4.3.2
os: darwin 24.3.0 15.3

node: 20.18.0
acorn: 8.12.1
ada: 2.9.0
ares: 1.33.1
base64: 0.5.2
brotli: 1.1.0
cjs_module_lexer: 1.4.1
cldr: 45.0
icu: 75.1
llhttp: 8.1.2
modules: 115
napi: 9
nghttp2: 1.61.0
nghttp3: 0.7.0
ngtcp2: 1.1.0
openssl: 3.0.13+quic
simdutf: 5.5.0
tz: 2024a
undici: 6.19.8
unicode: 15.1
uv: 1.46.0
uvwasi: 0.0.21
v8: 11.3.244.8-node.23
zlib: 1.3.0.1-motley-71660e1

更新版本后，执行了hexo三板斧，没有观测到butterfly主题4.9.0版本上有啥问题，已有站点能正常渲染，说明hexo版本升级ok了。那就可以开始更新butterfly主题的版本了。

2. 主题更新

下载5.3.5版本的压缩包，放到theme目录下，解压，文件夹命名为butterfly5，主题配置文件也命名为_config.butterfly5.yaml，这样就能和老版本的butterfly共存，有问题可以直接通过切主题名称切老版本去。

下面是先前我对butterfly主题魔改的记录，其实都算不上魔改，主要是新增了几个页面。

  1. 【Hexo】hexo-butterfly主题添加非主站提示
  2. 【Hexo】hexo-butterfly主题添加装备展示页面
  3. 【Hexo】hexo-butterfly主题添加tag标签文章数量上下标
  4. 【Hexo】hexo-butterfly主题添加影评书评页面

这边照着原本的博客和Hexo配置仓库的Git提交信息，对新版本的butterfly主题做相同的修改就OK了，没有任何差异，修改后直接就能用。

3. 配置问题记录

3.1. 站点背景图

注意，butterfly新版本配置中，站点背景图设置的时候直接填url就可以了，不用像老主题一样需要用url()​括起来，新版本已经自动帮我们处理了。

1
background: /img/main/mothra.webp

image

3.2. CDN配置

目前使用cdnjs和jsdeliver似乎都容易404，于是还是想找国内替代的cdn。

现在有两个方案，一个是使用custom自定义的url，另外一个是借助hexo-butterfly-extjs​插件使用本地的内容（hexo g的时候把js文件都拉至本地）

目前hexo-butterfly-extjs​能正常使用，但是加载速度非常慢

于是考虑使用custom，目前七牛云的cdn.staticfile.org​已经停止维护了，找到了一个还在维护的：www.zstatic.net/docs/getting-started

最开始我设置成了如下，结果发现虽然请求后返回的是200，但是返回的内容都是空的，并不是js的内容

1
https://s4.zstatic.net/${cdnjs_name}/${version}/${min_cdnjs_file}

image

最后看了一下butterfly的源码和zstatic站点上的介绍，首先butterfly源码中的cdn url是下面这样处理的

1
2
3
4
5
6
7
const cdnSource = {
    local: cond === 'internal' ? `${cdnjs_file + verType}` : `/pluginsSrc/${name}/${file + verType}`,
    jsdelivr: `https://cdn.jsdelivr.net/npm/${name}${verType}/${min_file}`,
    unpkg: `https://unpkg.com/${name}${verType}/${file}`,
    cdnjs: `https://cdnjs.cloudflare.com/ajax/libs/${cdnjs_name}/${version}/${min_cdnjs_file}`,
    custom: (CDN.custom_format || '').replace(/\$\{(.+?)\}/g, (match, $1) => value[$1])
  }

zstatis站点上给的示例是这样的

1
2
3
4
- https://cdnjs.cloudflare.com/ajax/libs/jquery/3.5.1/jquery.min.js
- https://cdn.bootcdn.net/jquery/3.5.1/jquery.min.js
- https://cdn.staticfile.net/jquery/3.5.1/jquery.min.js
+ https://s4.zstatic.net/ajax/libs/jquery/3.5.1/jquery.min.js

仔细一看会发现，zstatic用的url路径和cdnjs是一样的，所以我们要设置的自定义url也要和cdnjs维持一致

1
custom_format: https://s4.zstatic.net/ajax/libs/${cdnjs_name}/${version}/${min_cdnjs_file}

可以看到这个时候请求的url已经有内容了

image

目前测试结果正常，顶栏图标也能加载。

image

不过呢，后续测试发现zstatic的某些包是不支持的，比如我现在需要使用的mermaid包在zstatic里面会404，说明这个CDN没有成功缓存这个包。

所以，最后还是使用了butterfly的local CDN功能，CDN配置里面的两个provider都设置为local即可

1
2
3
4
5
6
7
CDN:
  # The CDN provider for internal and third-party scripts
  # Options for both: local/jsdelivr/unpkg/cdnjs/custom
  # Note: Dev version can only use 'local' for internal scripts
  # Note: When setting third-party scripts to 'local', you need to install hexo-butterfly-extjs
  internal_provider: local
  third_party_provider: local

local CDN是在hexo g​的时候，把所有用的到的js文件全部下载到本地，最终给用户提供的，全都是hexo静态目录下已经下载好的js文件了，不再需要使用外部CDN了，也就解决了访问问题和404问题。

目前没有发现local CDN有什么bug，使用正常。

3.3. Vercel和Netlify的node版本问题

最开始配置Vercel和Netlify的时候，配置的node版本是18，现在这两个站点都开始弃用node 18了，所有配置了node 18的项目会直接部署失败。

所以，需要去两个平台的后台，直接把构建设置里面的node版本改成22就可以了。hexo对node版本的兼容性很好，改了就能用，不需要做任何其他操作。

image.png

image.png

同理，cloudflare workers也是在设置里面把“构建系统版本”设置成更新的版本3。虽然当前workers使用版本2的node 18依旧可以正常部署，但还是设置一下吧！

image.png

这里也体现出claudeflare这个赛博大善人和其他平台的不同了，其他平台都因为各种原因弃用node 18支持的同时，claudeflare依旧安稳支持node 18，善！

3.4. packages-lock.json版本号匹配问题

另外需要注意的是，更新hexo和主题版本的时候一定要删除本地hexo仓库中的的packages-lock.json文件然后npm install重新安装（会生成新的packages-lock.json），否则cloudflare workers这类部署平台可能会因为版本号对不上而部署失败。

这个问题我只在cloudflare workers上遇到了，Vercel和Netlify都是正常能部署成功。但还是建议大家操作一下删除后重新npm install安装的步骤，避免出问题。