Hexo-5.x 与 NexT-8.x 跨版本升级
一年不见,发现 Hexo 和 NexT 跨版本更新,带来许多颠覆性(不兼容旧版)的更新,比如把 swig 模板换成 njk 模板、主题改用 npm 升级、废弃 next.yml 等,导致网上许多旧版 “教程” 失效,只好自己爬文摸索。这篇文章记录升级过程中遇到的坑和解决方法,主要包含以下内容:
- Node.js v10 升级到 Node.js v12
- Hexo 4.x 升级到 Hexo 5.x
- 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 | // 检查环境版本 |
Hexo-5.x 跨版本升级
升级版本
Hexo 升级比较简单,老方法 npm-check
、npm-upgrade
、npm-update
一键三连。按以下顺序逐步执行完成后,Hexo 版本及系统插件均会升级到最新。以后 NexT 8.0 换成 npm 安装,这波操作会顺带把 NexT 无缝升级。
1 | //以下指令均在Hexo目录下操作,先定位到Hexo目录 |
调整配置
升级后别急着 hexo g
,需要先调整站点配置文件 hexo/_config.yml
,否则会报错。另外新版有新的配置项,统一归纳在这里:
↓↓以下是废弃的字段,需要重新配置↓↓
1 | # Deprecated |
↓↓以下是新增的字段,根据自身需要添加↓↓
1 | # URL |
NexT-8.x 跨版本升级
NexT 8.x相比旧版的改动比较多,无法做到平滑升级,建议做好备份后全新安装,然后重新配置内容 | 旧版 | 新版 |
---|---|---|
安装方式 | git | npm、git |
安装目录 | themes/next | npm:node_modules/hexo-theme-next、git:themes/next |
模板格式 | swig | njk |
Font Awesome | 4.x | 5.x |
配置文件位置 | hexo/source/_data | hexo/ |
配置文件名称 | next.yml | _config.next.yml |
升级版本
备份后删除主题文件夹 /themes/next、数据目录文件夹 /source/_data,通过 npm 方式安装新版:
1 | //定位到hexo目录,npm安装主题 |
调整配置
将 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 | # 旧版 |
两款代码高亮插件 highlight 和 prism 可以分别配置常规和 dark-mode 主题,在站点配置文件 hexo/_config.yml 选择其中一种启用,这个网站可以预览所有高亮效果:传送门
1 | codeblock: |
引用外部 js 文件不用再写 CDN 链接了,直接在配置里选择所需引用来源服务商就行:
1 | vendors: |
其他内容和旧版配置差别不大,根据自身需要去调整
样式兼容
网站之前启用了数据目录,自定义 CSS 保存在 /soyrce/_data/styles.styl
,将样式文件从备份文件夹中恢复,并在_config.next.yml 中指定目录,需要根据新版样式稍作调整,成品见 NexT 主题自定义 CSS 样式分享
1 | # Define custom file paths. |
默认页处理
截止至 2020 年 9 月,阿里云 OSS 已升级 “子目录首页” 功能,开通功能后将文件 404 规则设置为 “Index” 就可以正常访问 www.abc.com/a/,OSS 会自动读取 www.abc.com/a/index.html。
不过实测发现 OSS 的 CDN 自动刷新机制没有伴随升级,更新 www.abc.com/a/index.html 不会刷新 www.abc.com/a/ 的 CDN 缓存。所以结论是:
- 如果你的 OSS 没有配置 CDN,只需在 OSS 控制面板开通 “子目录首页” 功能,不用单独为 Hexo-NexT 增加默认页
- 如果你的 OSS 已绑定 CDN,需要通过修改源文件实现自动刷新
以前涉及到 NexT 的源文件改动只有 post.swig
,现在要改 post.njk
和 post-meta.njk
两个地方,详见 Hexo-NexT 为 OSS 增加默认页
后记
升级后的直观感受是 hexo g
速度快了很多,而 NexT-8.x 解决了很多历史遗留问题,比如 fancybox、lazyload、Pjax 不再冲突,可以同时启用了,相册群组和多级菜单也变得正常,推荐更新。更多的特性可以参考 Next 官方文档 以及 GitHub 更新说明