SakuraTears的博客

越努力越幸运

Hexo博客升级踩坑记

发表于 更新于 分类于 阅读次数： Valine：
本文字数： 14k 阅读时长 ≈ 13 分钟

前言

前些时间一直在写博客，整理记录信息等，一直没有关心过博客架构版本的问题。

最近的一篇博文需要用到 MathJax，我原以为 MarkDown 是支持 MathJax 的，在本地编写时没有遇到任何问题。

但发布到GitHub上后，直接导致我整个blog挂掉了，检查发现Hexo如果要完美支持 MathJax，需要hexo-renderer-kramed等等东西。

还要修改blog架构的一些源码，感觉很复杂，并且配置也不是十分友好。

在浏览过程中，我发现 Hexo 版本已经发布到5.4.0了，我使用的 NexT 主题也已经到了7.x的版本。

心想一不做二不休，趁此次机会升级下blog架构。

开始以为很简单，结果直接导致我的blog没法启动/没法使用了，中间升级的过程特此记录下，希望能给也想升级Hexo blog的人一些帮助。

正文

起始

本次想要升级的最终结果如下：

名称当前版本升级版本
NodeJsv10.2.0v16.2.0
Hexov3.9.0v5.4.0
NexTv5.1.4v7.8.0

其中还伴随这一些插件的升级，由于一些低版本插件过时，可能存在被删除的风险，这也是本次升级的一个主要原因。

NodeJs的升级十分简单，直接在官网 NodeJs 上下载最新版安装即可。

当然如果想安装其他版本，直接在 NodeJs 以往的版本 上下载即可。

安装好最新版后，直接使用命令即可显示Node版本。

1
2
D:\blog\newblog>node -v
v16.2.0

我们安装npm-upgrade插件，使用npm-upgrade命令，可以看到依赖可以更新到的最新版本。

1
2
3
npm install -g npm-upgrade

npm-upgrade

开始我直接更新所有依赖，直接导致了Hexo blog不能正常启动。

新建Hexo博客框架

这儿我们从新搭建一个博客来解决blog框架的升级问题。

优点：

  1. 重新搭建，所有依赖都依据比较新的版本，且不会出现不兼容的情况。
  2. NexT v5.x 和 NexT v7.x 变化巨大，甚至仓库地址都发生了变化，我们需要重新拷贝主题文件。
  3. 我们之前搭建blog在里面修改了很多代码实现某些功能，很混乱，不方便查找和修改，升级后我们可以统一处理了。（这也是我升级的一个主要原因）
  4. 新版本NexT新增了一些功能，我们一些手动实现的效果现在可以直接使用配置false或者true解决了。
  5. 据说新版本blog加载速度有所提升，不知道真的假的。

说到这儿，那我们开始吧，开始当然要检查下 Hexo 命令，如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
D:\blog\blog>hexo -v
INFO  Validating config
hexo: 5.4.0
hexo-cli: 4.2.0
os: Windows_NT 10.0.19042 win32 x64
node: 16.2.0
v8: 9.0.257.25-node.16
uv: 1.41.0
zlib: 1.2.11
brotli: 1.0.9
ares: 1.17.1
modules: 93
nghttp2: 1.42.0
napi: 8
llhttp: 6.0.1
openssl: 1.1.1k+quic
cldr: 39.0
icu: 69.1
tz: 2021a
unicode: 13.0
ngtcp2: 0.1.0-DEV
nghttp3: 0.1.0-DEV

hexo-cli: 4.2.0 , hexo: 5.4.0 即为当前最新版本，不是的需要升级下 Hexo。

Hexo升级可以直接卸载重装即可。

1
2
3
4
5
npm uninstall hexo -g
npm install hexo -g

npm uninstall hexo-cli -g
npm install hexo-cli -g

升级好后，使用以下指令：

① hexo init blog

② cd blog

③ npm install

④ hexo s

可以看到一个v5.4.0版本的 Hexo 博客初始化框架在 http://localhost:4000/ 启动了。

打开blog文件夹下的package.json文件，可以看到blog的基本配置。

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
{
  "name": "hexo-site",
  "version": "0.0.0",
  "private": true,
  "scripts": {
    "build": "hexo generate",
    "clean": "hexo clean",
    "deploy": "hexo deploy",
    "server": "hexo server"
  },
  "hexo": {
    "version": ""
  },
  "dependencies": {
    "hexo": "^5.0.0",
    "hexo-generator-archive": "^1.0.0",
    "hexo-generator-category": "^1.0.0",
    "hexo-generator-index": "^2.0.0",
    "hexo-generator-tag": "^1.0.0",
    "hexo-renderer-ejs": "^1.0.0",
    "hexo-renderer-marked": "^4.0.0",
    "hexo-renderer-stylus": "^2.0.0",
    "hexo-server": "^2.0.0",
    "hexo-theme-landscape": "^0.0.3"
  }
}

这儿我们把 hexo 版本手动改成5.4.0，同时移除hexo-theme-landscape，这儿主题对我们没用。

我们观察我们原来的配置文件。

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
{
  "name": "hexo-site",
  "version": "0.0.0",
  "private": true,
  "hexo": {
    "version": "3.9.0"
  },
  "dependencies": {
    "gulp": "^3.9.1",
    "gulp-htmlclean": "^2.7.22",
    "gulp-htmlmin": "^4.0.0",
    "gulp-imagemin": "^4.1.0",
    "gulp-minify-css": "^1.2.4",
    "gulp-uglify": "^3.0.0",
    "hexo": "^3.9.0",
    "hexo-admin": "^2.3.0",
    "hexo-autonofollow": "^1.0.1",
    "hexo-deployer-git": "^0.3.1",
    "hexo-generator-archive": "^0.1.4",
    "hexo-generator-baidu-sitemap": "^0.1.2",
    "hexo-generator-category": "^0.1.3",
    "hexo-generator-feed": "^1.2.2",
    "hexo-generator-index": "^0.2.0",
    "hexo-generator-searchdb": "^1.0.8",
    "hexo-generator-sitemap": "^1.2.0",
    "hexo-generator-tag": "^0.2.0",
    "hexo-helper-live2d": "^3.1.1",
    "hexo-renderer-ejs": "^0.3.0",
    "hexo-renderer-marked": "^0.3.0",
    "hexo-renderer-stylus": "^0.3.1",
    "hexo-server": "^0.2.0",
    "hexo-tag-aplayer": "^3.0.4",
    "hexo-wordcount": "^3.0.2"
  }
}

首先我们添加如下插件：

1
2
3
4
5
6
7
8
9
10
11
12
npm install hexo-admin --save   # blog 管理后台系统
npm install hexo-deployer-git --save  # blog发布到github使用
npm install hexo-excerpt --save      # 阅读更多插件
npm install hexo-generator-baidu-sitemap --save  # 百度站点地图（SEO）
npm install hexo-generator-feed --save     # RSS使用
npm install hexo-generator-searchdb --save  # 本地搜索插件
npm install hexo-generator-sitemap --save   # 站点地图
npm install hexo-helper-live2d --save      # 萌妹子插件
npm install hexo-related-popular-posts --save   # 标记最受欢迎的文章（侧边栏显示）
npm install hexo-symbols-count-time --save   # 统计插件（替代wordcount）
npm install hexo-tag-aplayer --save    # 一款优秀的音乐播放器插件
npm install hexo-autonofollow --save   # 不跟踪外链插件（SEO）

添加好后，我们需要下载NexT主题，新版的NexT主题可以在 https://github.com/theme-next/hexo-theme-next 找到，旧版本的为 https://github.com/iissnan/hexo-theme-next 需要注意。

我们直接copy到我们项目。

1
2
$ cd blog
$ git clone https://github.com/theme-next/hexo-theme-next themes/next

弄好后，我们开始配置blog下的_config.yml。

这个配置直接按照我们原先的blog，根据key对应过来就行。注意主题选择NexT。 theme: next

遇到的问题：

问题1： language: zh-CN 原来blog是 zh-Hans

更改后，需要在 blog\themes\next\languages\zh-CN.yml添加没有被翻译的文字。

问题2： avatar 头像

Hexo v5.4.0 移除了这个参数，这个参数现在由NexT主题控制，并可以通过配置实现旋转，十分方便。

问题3： excerpt 阅读更多功能

1
2
3
4
5
excerpt:
  depth: 5  #按层来算，也就是按代码块来算
  excerpt_excludes: []
  more_excludes: []
  hideWholePostExcerpts: true

PS: NexT 配置里也可以进行相关配置，但是涉及到具体显示多少行，只能在此配置。

下面主要说一下NexT的_config.yml配置，位置blog\themes\next_config.yml。

问题4： creative_commons 参数

1
2
3
4
5
6
7
8
9
10
# Creative Commons 4.0 International License.
# See: https://creativecommons.org/share-your-work/licensing-types-examples
# Available values of license: by | by-nc | by-nc-nd | by-nc-sa | by-nd | by-sa | zero
# You can set a language value if you prefer a translated version of CC license, e.g. deed.zh
# CC licenses are available in 39 languages, you can find the specific and correct abbreviation you need on https://creativecommons.org
creative_commons:
  license: by-nc-sa
  sidebar: true
  post: true
  language: deed.zh

这个参数会在文章结束后为自动为文章署名协议，不用我们改代码配置了。

问题5： menu配置图标变化

1
2
3
4
5
6
7
8
menu:
  home: / || fa fa-home
  about: /about/ || fa fa-user
  tags: /tags/ || fa fa-tags
  categories: /categories/ || fa fa-th
  archives: /archives/ || fa fa-archive
  support: /support/ || fa fa-bookmark
  photos: /photos/ || fa fa-camera

图标配置均变为fa fa-home这种格式，不注意会直接不显示图标，十分坑。

问题6：avatar 头像配置

1
2
3
4
5
6
7
avatar:
  # Replace the default image and set the url here.
  url: https://sakuratears.oss-cn-beijing.aliyuncs.com/blog/others/avatar.jpg
  # If true, the avatar will be dispalyed in circle.
  rounded: true
  # If true, the avatar will be rotated with the cursor.
  rotated: true

头像可以实现接触旋转，不用再手动修改NexT源代码了。

问题7： 阅读更多

1
2
3
4
5
6
# Automatically excerpt description in homepage as preamble text.
excerpt_description: true

# Read more button
# If true, the read more button will be displayed in excerpt section.
read_more_btn: true

主要由上面两项控制，hexo的配置文件里可以配置显示行数。

问题8： 文章字数统计

1
2
3
4
5
6
# Post wordcount display settings
# Dependencies: https://github.com/theme-next/hexo-symbols-count-time
symbols_count_time:
  separated_meta: true
  item_text_post: true
  item_text_total: true

改用symbols_count_time插件了，需要注意。

问题9：reward和follow me 也有变化，原来follow_me只支持微信公众号

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# Reward (Donate)
# Front-matter variable (unsupport animation).
reward_settings:
  # If true, reward will be displayed in every article by default.
  enable: true
  animation: true
  comment: 您的支持就是我创作的动力！

reward:
  wechatpay: https://sakuratears.oss-cn-beijing.aliyuncs.com/blog/others/wechatpay.png
  alipay: https://sakuratears.oss-cn-beijing.aliyuncs.com/blog/others/alipay.jpg
  #paypal: /images/paypal.png
  #bitcoin: /images/bitcoin.png

# Subscribe through Telegram Channel, Twitter, etc.
# Usage: `Key: permalink || icon` (Font Awesome)
follow_me:
  #Twitter: https://twitter.com/username || fab fa-twitter
  #Telegram: https://t.me/channel_name || fab fa-telegram
  WeChat: https://sakuratears.oss-cn-beijing.aliyuncs.com/blog/others/qrcode_wechat_subscriber.jpg || fab fa-weixin
  RSS: /atom.xml || fa fa-rss

问题10： 标签云

1
2
3
4
5
6
7
8
# TagCloud settings for tags page.
tagcloud:
  # All values below are same as default, change them by yourself.
  min: 18 # Minimun font size in px
  max: 36 # Maxium font size in px
  start: "#ADD8E6" # Start color (hex, rgba, hsla or color keywords)
  end: "#FFB6C1" # End color (hex, rgba, hsla or color keywords)
  amount: 300 # Amount of tags, change it if you have more than 200 tags

原来是更改NexT主题代码写死的，现在只要配置就可以了。

问题11： 有用的小功能

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
back2top:
  enable: true
  # Back to top in sidebar.
  sidebar: true
  # Scroll percent label in b2t button.
  scrollpercent: true

# Reading progress bar
reading_progress:
  enable: true
  # Available values: top | bottom
  position: top
  color: "#37c6c0"
  height: 3px

# Bookmark Support
bookmark:
  enable: true
  # Customize the color of the bookmark.
  color: "#222"
  # If auto, save the reading progress when closing the page or clicking the bookmark-icon.
  # If manual, only save it by clicking the bookmark-icon.
  save: manual

# `Follow me on GitHub` banner in the top-right corner.
github_banner:
  enable: true
  permalink: https://github.com/javazwt
  title: Follow me on GitHub

可以添加快速回到顶部的按钮back2top，阅读进度条reading_progress，书签bookmark还有github_banner。

原来要实现均要改源码。

问题12： needmoreshare2

安装 hexo-next-share 插件。

1
npm install theme-next/hexo-next-share

进行如下配置：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
needmoreshare:
  enable: true
  cdn:
    js: //cdn.jsdelivr.net/gh/theme-next/theme-next-needmoreshare2@1/needsharebutton.min.js
    css: //cdn.jsdelivr.net/gh/theme-next/theme-next-needmoreshare2@1/needsharebutton.min.css
  postbottom:
    enable: false
    options:
      iconStyle: box
      boxForm: vertical
      position: bottomCenter
      networks: Weibo,Wechat,Douban,QQZone,Twitter,Facebook
  float:
    enable: true
    options:
      iconStyle: default
      boxForm: horizontal
      position: topRight
      networks: Weibo,Wechat,Douban,QQZone,Twitter,Facebook

分享图标便会出现在左下角。

问题13： theme-next-pace

引入pace插件，使页面加载的时候显示进度条

1
2
cd themes/next
git clone https://github.com/theme-next/theme-next-pace source/lib/pace

开启配置

1
2
3
4
5
6
pace:
enable: true
# Themes list:
# big-counter | bounce | barber-shop | center-atom | center-circle | center-radar | center-simple
# corner-indicator | fill-left | flat-top | flash | loading-bar | mac-osx | material | minimal
theme: mac-osx

问题14： 用户自定义实现 custom_file_path

这是我要重点说的，该配置可以让用户有规则的配置其他内容，也方便我们以后的blog迁移，尽量做到无侵入。

1
2
3
4
5
6
7
8
9
10
11
12
13
# 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.swig
  #header: source/_data/header.swig
  sidebar: source/_data/sidebar.swig
  #postMeta: source/_data/post-meta.swig
  postBodyEnd: source/_data/post-body-end.swig
  #footer: source/_data/footer.swig
  bodyEnd: source/_data/body-end.swig
  #variable: source/_data/variables.styl
  #mixin: source/_data/mixins.styl
  style: source/_data/styles.styl

比如我们想在侧边栏添加音乐，想在文末添加阅读结束标记，添加背景，添加鼠标点击效果等，以前的做法参见这几篇文章。

搭建自己的Hexo博客（1）
搭建自己的Hexo博客（2）
搭建自己的Hexo博客（3）
搭建自己的Hexo博客（4）

现在只要在source/_data文件夹下（也可以不是这个文件夹，但是强烈建议放在source文件夹下，这里面存放着的都是与框架无关的东西）即可。

最终效果如下：

SakuraTears’blog

博文压缩优化

原来我们blog使用的是gulp管理，还写了一些代码，不方便管理，现在我们引入hexo-neat来压缩博文。

1
npm install hexo-neat --save

同时在Hexo配置文件里配置如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# hexo-neat
# 博文压缩
neat_enable: true
# 压缩html
neat_html:
  enable: true
  exclude:
# 压缩css  
neat_css:
  enable: true
  exclude:
    - '**/*.min.css'
# 压缩js
neat_js:
  enable: true
  mangle: true
  output:
  compress:
  exclude:
    - '**/*.min.js'

配置就不详解了，我们使用hexo g命令，可以看到public文件夹下的内容已被压缩。

其它不足

问题1： 音乐栏不对齐

这个问题我也比较诧异，原来博客是好的，我在这块没做改动，还要看看CSS样式仔细研究一下。

问题2：阅读更多上面没法正好兼容图片

问题3：整体上感觉字体过大。

问题处理

阅读更多图片问题

对于上面的第二个问题，后面我在查找资料时看到如下文章：

Hexo excerpt <!—- more –> not working after update

因此我想到查看hexo-excerpt代码是否有对于阅读更多的处理，搜索hexo-excerpt.js，在node_modules里找到该类。

可以看到是有对阅读更多进行处理的。

后面我想到是不是depth过深导致问题的原因，我把配置的depth改为了3。

1
2
3
4
5
excerpt:
  depth: 3  #按层来算，也就是按代码块来算
  excerpt_excludes: []
  more_excludes: []
  hideWholePostExcerpts: true

重新启动blog果然好了。

但引发的另一个问题就是其他一些文字摘要显示的太少了……

后面我仔细想了下，原来配置用的auto_excerpt。

1
2
3
4
5
# Automatically Excerpt (Not recommend).
# Use <!-- more --> in the post to control excerpt accurately.
auto_excerpt:
  enable: true
  length: 150

其摘要是查找150个字后显示阅读更多。不会考虑格式，因此基本就是3行，所以我原来的blog没有出现这种问题。

hexo-excerpt在检索时保留了原文的格式，按照深度来进行处理。

但是如果没有图片，只有文字的话，比如深度是5，我在深度3的位置添加 more 标签，只显示深度3的部分，说明插件是没问题的。

后面我终于想到了一种解决办法。

就是如果文章开头就是图片，而且只想要摘要显示这张图片，depth又比较深的话，摘要里会显示文字部分。

我在图片后面加了两个more解决问题。

1
2
3
![](https://sakuratears.oss-cn-beijing.aliyuncs.com/blog/title/show1.jpg)

<!-- more --><!--more-->

canvas_nest 支持

下载canvas_nest插件。

1
2
cd themes/next
git clone https://github.com/theme-next/theme-next-canvas-nest source/lib/canvas-nest

使用用户自定义的方式引入：

新建 footer.swig

1
2
3
{% if theme.canvas_nest %}
<script color="0,0,255" opacity="0.5" zIndex="-1" count="99" src="/lib/canvas-nest/canvas-nest.min.js"></script>
{% endif %}

在NexT主题的_config.yml配置如下：

1
2
3
4
5
custom_file_path:
  footer: source/_data/footer.swig

# Canvas-nest
canvas_nest: true

并将footer.swig放到Hexo的source/_data文件夹下。

如果不想在本地，也可以使用cdn。

1
2
3
{% if theme.canvas_nest %}
<script color="0,0,255" opacity="0.5" zIndex="-1" count="99" src="https://cdn.jsdelivr.net/npm/canvas-nest.js@1/dist/canvas-nest.js"></script>
{% endif %}

添加网站底部建站时间支持

同上，将如下代码放置footer.swig。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{% if theme.time_date %}
<br>
<span id="timeDate">载入天数...</span><span id="times">载入时分秒...</span>
<script>
    var now = new Date(); 
    function createtime() { 
        var grt= new Date("05/20/2018 00:00:00");//此处修改你的建站时间或者网站上线时间 
        now.setTime(now.getTime()+250); 
        days = (now - grt ) / 1000 / 60 / 60 / 24; dnum = Math.floor(days); 
        hours = (now - grt ) / 1000 / 60 / 60 - (24 * dnum); hnum = Math.floor(hours); 
        if(String(hnum).length ==1 ){hnum = "0" + hnum;} minutes = (now - grt ) / 1000 /60 - (24 * 60 * dnum) - (60 * hnum); 
        mnum = Math.floor(minutes); if(String(mnum).length ==1 ){mnum = "0" + mnum;} 
        seconds = (now - grt ) / 1000 - (24 * 60 * 60 * dnum) - (60 * 60 * hnum) - (60 * mnum); 
        snum = Math.round(seconds); if(String(snum).length ==1 ){snum = "0" + snum;} 
        document.getElementById("timeDate").innerHTML = "本站已运行 "+dnum+" 天 "; 
        document.getElementById("times").innerHTML = hnum + " 小时 " + mnum + " 分 " + snum + " 秒"; 
    } 
setInterval("createtime()",250);
</script>
{% endif %}

在NexT主题的_config.yml配置如下：

1
2
3
4
5
custom_file_path:
  footer: source/_data/footer.swig

# 建站时间支持
time_date: true

总结

关于blog框架的更新基本就到这儿了，后面如果再有更新我会继续更新到此博文里。

原来的blog源码我没有删除，而是进行了备份。




-------------文章结束啦 ~\(≧▽≦)/~ 感谢您的阅读-------------

您的支持就是我创作的动力！

欢迎关注我的其它发布渠道