Hexo-5.x 与 NexT-8.x 跨版本升级

发表于 更新于 分类于
本文字数： 1.9k 阅读时长 ≈ 2 分钟

Photo by Max Ducourneau on Unsplash

一年不见，发现 Hexo 和 NexT 跨版本更新，带来许多颠覆性（不兼容旧版）的更新，比如把 swig 模板换成 njk 模板、主题改用 npm 升级、废弃 next.yml 等，导致网上许多旧版 “教程” 失效，只好自己爬文摸索。这篇文章记录升级过程中遇到的坑和解决方法，主要包含以下内容：

  1. Node.js v10 升级到 Node.js v12
  2. Hexo 4.x 升级到 Hexo 5.x
  3. NexT 7.x 升级到 NexT 8.x

Node 升级

Hexo 5.x支持的Node.js版本是v10以上，由于Node.js v10 计划2021年停止更新，官方建议使用Node.js v12。如果环境版本低于v12，可以下载长期支持版（LTS）覆盖安装。

Node.JS 官网

1
2
// 检查环境版本
> node -v

Hexo-5.x 跨版本升级

升级版本

Hexo 升级比较简单，老方法 npm-check、npm-upgrade、npm-update 一键三连。按以下顺序逐步执行完成后，Hexo 版本及系统插件均会升级到最新。以后 NexT 8.0 换成 npm 安装，这波操作会顺带把 NexT 无缝升级。

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
//以下指令均在Hexo目录下操作，先定位到Hexo目录
//查看当前版本，判断是否需要升级
> hexo version

//全局升级hexo-cli
> npm i hexo-cli -g

//再次查看版本，看hexo-cli是否升级成功
> hexo version

//安装npm-check，若已安装可以跳过
> npm install -g npm-check

//检查系统插件是否需要升级
> npm-check

//安装npm-upgrade，若已安装可以跳过
> npm install -g npm-upgrade

//更新package.json
> npm-upgrade

//更新全局插件
> npm update -g

//更新系统插件
> npm update --save

//再次查看版本，判断是否升级成功
> hexo version

调整配置

升级后别急着 hexo g，需要先调整站点配置文件 hexo/_config.yml，否则会报错。另外新版有新的配置项，统一归纳在这里：

↓↓以下是废弃的字段，需要重新配置↓↓

1
2
3
4
5
6
7
8
9
10
11
12
13
# Deprecated
external_link: true|false
# New option
external_link:
  enable: true # Open external links in new tab
  field: site # Apply to the whole site
  exclude: ''

# Deprecated
use_date_for_updated: true
# New option
## pdated_option supports 'mtime', 'date', 'empty'
updated_option: 'mtime'

↓↓以下是新增的字段，根据自身需要添加↓↓

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
# URL
pretty_urls:
  trailing_index: true 
  trailing_html: true

# Writing
highlight:
  enable: true
  auto_detect: false
  line_number: true
  tab_replace: '  '
  wrap: true
  hljs: false
prismjs:
  enable: false
  preprocess: true
  line_number: true
  tab_replace: ''

# Metadata elements
## https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta
meta_generator: true

# Include / Exclude file(s)
## include:/exclude: options only apply to the 'source/' folder
include:
exclude:
ignore:

NexT-8.x 跨版本升级

NexT 8.x相比旧版的改动比较多，无法做到平滑升级，建议做好备份后全新安装，然后重新配置
内容旧版新版
安装方式 gitnpm、git
安装目录 themes/nextnpm:node_modules/hexo-theme-next、git:themes/next
模板格式 swignjk
Font Awesome4.x5.x
配置文件位置 hexo/source/_datahexo/
配置文件名称 next.yml_config.next.yml

升级版本

备份后删除主题文件夹 /themes/next、数据目录文件夹 /source/_data，通过 npm 方式安装新版：

1
2
//定位到hexo目录,npm安装主题
> npm install hexo-theme-next

调整配置

将 Next 主题配置文件 node_modules/hexo-theme-next/_config.yml 改名为 _config.next.yml, 复制到根目录（与 Hexo 站点配置文件_config.yml 在同一目录），这个文件的作用等同于旧版 next.yml，但优先级最高。这样做的好处是以后可以通过 npm 顺滑升级 Next 版本，不用担心配置文件被覆盖。

找上一步备份的旧版主题配置文件，对照内容重新配置 _config.next.yml，有几个地方需要留意：

凡涉及到引用 Font Awesome 的地方，图标名和调用方式要更新，比如旧版填写 home，新版要改为 fa fa-home，否则图标会显示空白。可以在 官方网站 找到最新图标名

1
2
3
4
5
6
7
# 旧版
menu:
  home: / || home

# 新版
menu:
  home: / || fa fa-home

两款代码高亮插件 highlight 和 prism 可以分别配置常规和 dark-mode 主题，在站点配置文件 hexo/_config.yml 选择其中一种启用，这个网站可以预览所有高亮效果：传送门

1
2
3
4
5
6
7
8
9
10
11
12
13
14
codeblock:
  # Code Highlight theme
  # All available themes: https://theme-next.js.org/highlight/
  theme:
    light: androidstudio
    dark: androidstudio
  prism:
    light: prism-material-oceanic
    dark: prism-dark
  # Add copy button on codeblock
  copy_button:
    enable: true
    # Available values: default | flat | mac
    style: flat

引用外部 js 文件不用再写 CDN 链接了，直接在配置里选择所需引用来源服务商就行:

1
2
3
4
5
6
7
8
9
vendors:
  # The CDN provider of NexT internal scripts.
  # Available values: local | jsdelivr | unpkg
  # Warning: If you are using the latest master branch of NexT, please set `internal: local`
  internal: local
  # The default CDN provider of third-party plugins.
  # Available values: local | jsdelivr | unpkg | cdnjs
  # Dependencies for `plugins: local`: https://github.com/next-theme/plugins
  plugins: jsdelivr

其他内容和旧版配置差别不大，根据自身需要去调整

样式兼容

网站之前启用了数据目录，自定义 CSS 保存在 /soyrce/_data/styles.styl，将样式文件从备份文件夹中恢复，并在_config.next.yml 中指定目录，需要根据新版样式稍作调整，成品见 NexT 主题自定义 CSS 样式分享

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# Define custom file paths.
# Create your custom files in site directory `source/_data` and uncomment needed files below.
custom_file_path:
  #head: source/_data/head.njk
  #header: source/_data/header.njk
  #sidebar: source/_data/sidebar.njk
  #postMeta: source/_data/post-meta.njk
  #postBodyEnd: source/_data/post-body-end.njk
  #footer: source/_data/footer.njk
  #bodyEnd: source/_data/body-end.njk
  #variable: source/_data/variables.styl
  #mixin: source/_data/mixins.styl
- #style: source/_data/styles.styl
+ style: source/_data/styles.styl

默认页处理

截止至 2020 年 9 月，阿里云 OSS 已升级 “子目录首页” 功能，开通功能后将文件 404 规则设置为 “Index” 就可以正常访问 www.abc.com/a/，OSS 会自动读取 www.abc.com/a/index.html。

OSS开启子目录首页

不过实测发现 OSS 的 CDN 自动刷新机制没有伴随升级，更新 www.abc.com/a/index.html 不会刷新 www.abc.com/a/ 的 CDN 缓存。所以结论是：

  1. 如果你的 OSS 没有配置 CDN，只需在 OSS 控制面板开通 “子目录首页” 功能，不用单独为 Hexo-NexT 增加默认页
  2. 如果你的 OSS 已绑定 CDN，需要通过修改源文件实现自动刷新

以前涉及到 NexT 的源文件改动只有 post.swig，现在要改 post.njk 和 post-meta.njk 两个地方，详见 Hexo-NexT 为 OSS 增加默认页

后记

升级后的直观感受是 hexo g 速度快了很多，而 NexT-8.x 解决了很多历史遗留问题，比如 fancybox、lazyload、Pjax 不再冲突，可以同时启用了，相册群组和多级菜单也变得正常，推荐更新。更多的特性可以参考 Next 官方文档 以及 GitHub 更新说明

相关文章