Hexo 博客 NexT 主题的安装使用

发表于 更新于 分类于

hexo 安装

hexo 的安装比较简单，直接按照官网的说明步骤安装即可。首先是基础软件 nodejs 以及 git，这两个都是常用基础软件所以就不介绍细节了，官网直接安装即可。 按照使用了 npm 这个 nodejs 库管理软件，由于默认源在国外经常连接超时，所以首先需要修改成国内的镜像源，这里是改成了淘宝的镜像源

npm config set registry https://registry.npm.taobao.org

接下来就是使用 npm 命令安装 hexo 了：

npm install -g hexo-cli

Linux 下安装到个人目录

值得注意的是在 linux 下直接安装会有权限问题（npm 默认会放到 /usr/lib/node_modules 目录下，普通用户没有权限也不建议修改权限或使用 sudo），最好按照 npm 官方的指南安装到用户个人目录下。 新建一个用来存放下载安装文件的目录：

mkdir ~/.npm-global

修改 npm 安装设置：

npm config set prefix '~/.npm-global'

打开 / 新建文件 ~/.profile 并在最后加入如下一行以添加环境变量：

export PATH=~/.npm-global/bin:$PATH

刷新环境变量

source ~/.profile

hexo 初始化

成功按照好 hexo 后，找一个合适的地方存放博客文件，初始化新建一个名为 blog 的项目：

hexo init blog

这样就新生成了一个名为 blog 的文件夹，里边存放一些初始化的 hexo 博客文件。可以在本地打开查看：

cd blog
hexo server

这样会默认在本地生成一个博客系统，可以根据提示打开浏览器查看（默认在 http://localhost:4000/）

安装 NexT 主题

个人使用的 hexo 主题是 NexT，安装步骤参考官方的说明文档，安装最新的一个 release 版本：

git clone --branch v8.11.1 https://github.com/next-theme/hexo-theme-next themes/next

成功安装后将 hexo 配置文件中的主题改为 next 就成功了。

theme: next

Hexo 配置

生成的 hexo 主目录下有一个名为_config.yml 的文件，需要修改一些参数，具体细节可以参考官方文档，下面是部分我使用修改的参数。

同步生成文件夹

将每篇博客对应生成一个文件夹目录（方便插入图片等附件）：

post_asset_folder: true

以方便插入图片，在文件夹内放入图片，md 文件中加入 {% asset_img filename.png %} 就可以了，但是这样在 md 文件中看不到图片，目前我还未找到合适的解决办法，搭配 hexo s 命令在本地实时生成站点凑合着用。

修正路径（渲染器设置）

查询 hexo 默认渲染器 marked1 的文档后，发现了目前增加了配置选项，关键起作用的是这两项：

marked:
  prependRoot: true
  postAsset: false

但是默认渲染器对于很多 markdown 语法支持很差（对于我个人主要缺少数学公式以及引用脚注的支持，所以我把渲染器改成了 pandoc2，此渲染器目前对于图片的引用还处在 Hexo 原版，只能使用 asset_img 插入，由于路径的问题，markdown 语言本地软件和渲染生成的网页总有一个有问题）

修正路径（typora 设置）

如果使用的渲染器不是 hexo-renderer-marked，有一种曲线救国的方式就是修改本地 markdown 阅读器的设置，比如 typora 就支持一个参数 typora-root-url 可以修改默认的识别路径，将此项设置成博客文章的题目名（也是同步生成的文件夹名字），这样 typora 就能正确加载图片，渲染出的网页也没有问题。

每次都修改此项设置比较麻烦，所以我把此项加入到了生成模板中，修改 scaffolds/post.md 文件，在文件头中加入这样一行：

typora-root-url: {{ title }}

更换渲染器

修改 markdown 渲染器为 hexo-renderer-pandoc。值得注意的是需要将旧渲染器 marked 卸载掉再安装，另外系统中需要有 pandoc 这个软件来辅助转化。

npm un hexo-renderer-marked --save
npm i hexo-renderer-pandoc --save

部署

我个人博客放在了学校的 FTP 主页上，只支持 ftp 上传，但是 hexo 官方提供的 ftp 部署有些问题，上传在新建目录后直接卡住，我参考一些文章的修改细节 3，修改了一下源（原 npm 源上次代码更新居然停留在 2015 年！），把根目录下 package.json 文件内这一项修改如下：

"dependencies": {
    ...
   "hexo-deployer-ftpsync": "git+ssh://git@github.com:ChaosTong/hexo-deployer-ftpsync.git",
   ...

接下来重新安装 npm install hexo-deployer-ftpsync --save，这样部署插件就能正常工作了，通过命令 hexo d 部署可以一步到位。

NexT 配置

NeXT 主题的配置就是找到位于 themes/next 文件夹内的_config.yml 文件，按照顺序从上到下修改配置即可。下面是部分我使用的。

阅读时间统计

给博客文章添加一下字数以及阅读时间统计 4，虽然统计得不太准。npm 安装：

npm install hexo-symbols-count-time

在 Hexo 的配置文件中加入下面的配置（这里的字长已经评价时间是按照中文配置的，英文 / 中英混合需要修改 awl 以及 wpm 参数）：

symbols_count_time:
  symbols: true
  time: true
  total_symbols: true
  total_time: true
  exclude_codeblock: false
  awl: 3
  wpm: 200
  suffix: "mins."

确认 NexT 的配置（默认就是这个不必添加修改，确认一下存在无误即可）：

symbols_count_time:
  separated_meta: true
  item_text_post: true
  item_text_total: false

盘古插件

方便显示，在中英文已经数字符合等合适位置加入一下空格间隔以美化 UI。

pangu: true

Valine 评论系统

由于安全性以及加载速度等原因，本站已改用 Waline 作为评论系统，下面 Valine 相关可能不再有效！ 博客是静态的，所以需要通过一些插件来实现评论功能，我一直使用的是 Valine。具体细节可以参考 Valine 的文档，就是在 Leancloud 上注册一个帐号，建一个仓库作为评论数据的存储位置。因国内的参考需要域名需要备案，所以我就选择了 Leancloud 美区。

自定义 url

国际版 Leancloud 认使用的链接是 us.leancloud.cn，目前已经停止解析，参考仓库 issue5 在 serverURLs 选项设置为 https:// 你的 AppID 前 8 位.api.lncldglobal.com。

修改默认显示

默认的评论在文章下面显示为 Valine，普通访问者显然不知道这是评论，所以需要适当修改显示文字，参考官方文档说明，在 source/_data 目录下新建一个名为 languages.yml 的文件，内容如下（我为了对称将阅读次数改成了阅读数）：

# language
zh-CN:
  # items
  post:
    views: 阅读数
    comments:
      valine: 评论数

评论邮件提醒

先去一直没有配置评论邮件提醒，因为这个博客主要是记录自己的各种问题的，没想到会有好多人来看，由于个人比较忙也没时间管理后台及时回复评论，所以接这次重新整理博客给整个站点加上邮件提醒。 评论邮件提醒 6 的配置方法是每天一次检查过去 24 小时没有的提醒（个人站点没几个评论这样足够用了，没有必要占用资源一直处在唤醒状态）。 这里基本按照文档一步一步来就行，值得注意的是我的博客放在了学校的子目录下，所以文章链接出现了一点小问题，变量 SITE_URL 首页应该设置成学校的首页 http://home.ustc.edu.cn，然后在邮件模板中把自己的首页修改一下即可。

Waline 评论系统

由于 valine 评论存在种种问题，故本站将评论系统变更成 waline。由于先前使用的是 valine，二者一脉相承迁移非常方便，参考官网教程在 vercel 服务端一键部署即可。

在 NexT 主题中使用，首先安装插件

npm install @waline/hexo-next

然后在 NexT 主题配置中加入：

# Waline Config File
# For more information:
# - https://waline.js.org
# - https://waline.js.org/reference/component.html
waline:
  # New! Whether enable this plugin
  enable: false

  # Waline server address url, you should set this to your own link
  serverURL: https://waline.vercel.app

  # Waline library CDN url, you can set this to your preferred CDN
  libUrl: https://unpkg.com/@waline/client@v2/dist/waline.js

  # Waline CSS styles CDN url, you can set this to your preferred CDN
  cssUrl: https://unpkg.com/@waline/client@v2/dist/waline.css

  # Custom locales
  # locale:
  #   placeholder: Welcome to comment # Comment box placeholder

  # If false, comment count will only be displayed in post page, not in home page
  commentCount: true

  # Pageviews count, Note: You should not enable both `waline.pageview` and `leancloud_visitors`.
  pageview: false

  # Custom emoji
  # emoji:
  #   - https://unpkg.com/@waline/emojis@1.0.1/weibo
  #   - https://unpkg.com/@waline/emojis@1.0.1/alus
  #   - https://unpkg.com/@waline/emojis@1.0.1/bilibili
  #   - https://unpkg.com/@waline/emojis@1.0.1/qq
  #   - https://unpkg.com/@waline/emojis@1.0.1/tieba
  #   - https://unpkg.com/@waline/emojis@1.0.1/tw-emoji

  # Comment infomation, valid meta are nick, mail and link
  # meta:
  #   - nick
  #   - mail
  #   - link

  # Set required meta field, e.g.: [nick] | [nick, mail]
  # requiredMeta:
  #   - nick

  # Language, available values: en-US, zh-CN, zh-TW, pt-BR, ru-RU, jp-JP
  # lang: zh-CN

  # Word limit, no limit when setting to 0
  # wordLimit: 0

  # Whether enable login, can choose from 'enable', 'disable' and 'force'
  # login: enable

  # comment per page
  # pageSize: 10

注意具体的参数要自定义成自己个人的， 本人添加了微波、B 站、qq、贴吧四类表情，打开了图片上传选项，然后把 liburl 和 cssurl 的 cdn 改成了 cdnjs 的国内镜像 sourcegcdnbaomitu，在此感谢此镜像提供的服务，但这个镜像指定最新的版本总解析错误，目前只好将 waline 的版本号写死。另外由于表情文件没有同步，所以改用了一个 unpkg 的镜像，将 unpkg.com 替换为 npm.elemecdn.com，这样在响应速度上几乎不影响日常使用了。

修改默认显示

默认的评论在文章下面显示为 Waline，普通访问者显然不知道这是评论，所以需要适当修改显示文字，参考官方文档说明，在 source/_data 目录下新建一个名为 languages.yml 的文件，内容如下（我为了对称将阅读次数改成了阅读数）：

# language
zh-CN:
  # items
  post:
    views: 阅读数
    comments:
      waline: 评论数

搜索功能

NexT 主题自带了一个搜索功能 Local Search，即在编译文件时本地生成一个数据库，放在网站根目录下，用户借助此数据库进行搜索查询。 安装：

npm install hexo-generator-searchdb

在 NexT 的配置文件中打开：

local_search:
  enable: true

其余的配置就根据个人需求参考官方文档配置就好了。

Canvas nest 背景动画

为了使背景不那么单调，加入了一个几乎不影响性能的背景动画，配置细节参考官方说明。 在 source/_data 目录 (若不存在则新建一个) 下新建文件 footer.njk，内容（默认来自 jsdelivr 但是最近似乎国内访问出现问题，故改成了来自一个国内的 cdnjs 镜像 baomitu）：

<script color="0,0,255" opacity="0.5" zIndex="-1" count="99" src="https://lib.baomitu.com/canvas-nest.js/1.0.1/canvas-nest.js"></script>

然后在 NexT 的配置文件中找到 custom_file_path 一项将 footer 一行取消注释：

custom_file_path:
  footer: source/_data/footer.njk

分享按钮

参考此仓库的的配置，首先安装代码：

npm install theme-next/hexo-next-share

接下来写入配置文件，我使用的是 share.js（默认的 cdn 由 jsdelivr 改为 cdnjs 镜像 baomitu）

# share.js
# See: https://github.com/overtrue/share.js
# networks: weibo,qq,wechat,tencent,douban,qzone,linkedin,diandian,facebook,twitter,google
sharejs:
  enable: true
  cdn:
    js: https://lib.baomitu.com/social-share.js/1.0.16/js/social-share.min.js
    css: https://lib.baomitu.com/social-share.js/1.0.16/css/share.min.css
  networks: weibo,qq,wechat,tencent,douban,qzone,linkedin,diandian,facebook,twitter,google
  wechat_qrcode:
    title: share.title
    prompt: share.prompt

文末添加今日诗词

给个人博客添加一些人文气息，文末调用今日诗词的 API 根据访问的时间地点等智能推荐一句诗词，参考官方提供的接口文档，使用高级安装代码以显示更多信息。

首先通过主题配置将自定义页尾项取消注释：

custom_file_path:
  postBodyEnd: source/_data/post-body-end.njk

然后新建文件 source/_data/post-body-end.njk，并在其中加入下面内容即可

<script src="//sdk.jinrishici.com/v2/browser/jinrishici.js"></script>
<script>
  jinrishici.load((result) => {
    let jrsc = document.getElementById('jrsc');
    const data = result.data;
    let author = data.origin.author;
    let title = '《' + data.origin.title + '》';
    let content = data.content.substr(0, data.content.length - 1);
    let dynasty = data.origin.dynasty.substr(0, data.origin.dynasty.length - 1);
    jrsc.innerText = content + ' @ ' + dynasty + '·' + author + title;
  });
</script>
<div style="text-align: center"><span id="jrsc" >正在加载今日诗词....</span></div>

添加版权协议

为自己博客文章添加创作许可协议，个人使用的是署名 - 非商业性 - 相同方式共享协议，直接在配置文件中找到 creative_commons 部分把 post 设置为 true 即可，这样文末会自动添加协议。

如果个别博客文章是转载，只需要在博客头部加入 author 以及 url 即可。另外如需要关闭版权协议，也只需要在对应博客头中设置 copyright: false。

数学公式

markdown-it 默认的渲染器 Katex 在 Hexo 主题下表现不好，稍微复杂的一些公式渲染不出来，所以最终使用的是 NexT 主题提供的 MathJax 公式渲染器 7。

安装：

npm install hexo-filter-mathjax
hexo clean

如果需要使用 MathJax 来加载公式，对应文档的的文件头加入一个选项：mathjax: true，可以根据个人需求是否加入位于 scaffolds/post.md 文件模板中。

插入学校提供的访问计数框

原先我直接把计数框放在了 copyright 的作者后边，但是现在新版本加入了字数一级阅读时间，中间的框比较突兀，所以我去修改了一下前端模板的细节，找到 themes/next/layout/_partials/footer.njk 文件，先将 class 为 “wordcount” 的块去除属性与上一个 class 为 “copyright” 的块合并在一起，使得页尾的行数不会那么多，然后在中间作者一项后计数一项前加入下面一段

<span class="post-meta-item">
	<span class="post-meta-item-icon">
	  <i class="fa fa-eye"></i>
	</span>
	<img src="/cgi-bin/Count.cgi?df=liujunyan.dat&ft=0&tr=Y&trgb=ffffff&dd=cd&pad=0" style="display: inline-block; vertical-align: middle" title="站点总访问量">
</span>

其中为使计数器与周围兼容性好一些不那么突兀，个人小修改了一下图片的属性。 p.s. 我整理时才发现我之前的计数写错用户了，几千次的访问记到其他人的地方去了😭。

生成 RSS

参考 hexo 提供的代码仓库，安装插件：

npm install hexo-generator-feed

在 hexo 配置文件中设置，这是官方给的示例：

feed:
  enable: true
  type: atom
  path: atom.xml
  limit: 20
  hub:
  content:
  content_limit: 140
  content_limit_delim: ' '
  order_by: -date
  icon: icon.png
  autodiscovery: true
  template:

个人把 rss 订阅的按钮放在了左侧菜单中，所以 NexT 主题设置中 menu 项下面加入了下面一行：

RSS: /atom.xml || fa fa-rss

生成站点地图

站点地图描述了网站的结构，会帮助搜索引擎的爬虫去找到网站中的各个页面。 具体配置可以参考仓库，安装：

npm install hexo-generator-sitemap --save

修改 cdn

NexT 默认的 cdn 提供商包括 jsdelivr、unpkg、cdnjs，但是这些服务在国内访问速度都较慢，无法为用户加速反而使访问速度大打折扣，使得用户体验不佳，在互联网上搜寻多个国内的镜像均有各种问题，最终我选取了一个国内基于阿里云 cdn 的 cdnjs 镜像服务 sourcegcdn360 提供的前端 cdnjs 镜像 baomitu，NexT 中的设置如下：

vendors:
  internal: local
  plugins: custom
  custom_cdn_url: https://lib.baomitu.com/${cdnjs_name}/${version}/${cdnjs_file}
  1. 默认渲染器 github 地址：https://github.com/hexojs/hexo-renderer-marked[↩](http://home.ustc.edu.cn/~liujunyan/blog/hexo-next-theme-config/#fnref1)
  2. markdown pandoc 渲染器：https://github.com/wzpan/hexo-renderer-pandoc[↩](http://home.ustc.edu.cn/~liujunyan/blog/hexo-next-theme-config/#fnref2)
  3. hexo 修正的 ftp 同步工具 https://github.com/ChaosTong/hexo-deployer-ftpsync[↩](http://home.ustc.edu.cn/~liujunyan/blog/hexo-next-theme-config/#fnref3)
  4. 博客字数以及阅读时间估计插件：https://github.com/theme-next/hexo-symbols-count-time[↩](http://home.ustc.edu.cn/~liujunyan/blog/hexo-next-theme-config/#fnref4)
  5. 国际版 Leancloud 域名过期问题以及解决方案 https://github.com/xCss/Valine/issues/340[↩](http://home.ustc.edu.cn/~liujunyan/blog/hexo-next-theme-config/#fnref5)
  6. Valine 评论邮件提醒：https://github.com/DesertsP/Valine-Admin[↩](http://home.ustc.edu.cn/~liujunyan/blog/hexo-next-theme-config/#fnref6)
  7. 针对 NexT 主题配置的 MathJax 仓库：https://github.com/next-theme/hexo-filter-mathjax[↩](http://home.ustc.edu.cn/~liujunyan/blog/hexo-next-theme-config/#fnref7)