Hexo博客踩坑笔记

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

Hexo提供了非常方便的Markdown写作方式，我们只需提供md文件，而Hexo则为我们生成个人博客并渲染md成为文章。因为生成的网页为全静态文件，所以可以很方便地部署到github pages上，省去了维护vps的麻烦。此文用来记录一些注意事项，就是我在部署博客时花费较长时间解决问题的笔记，方便日后参考。
注意当前Hexo版本更新到5.1.1，NexT更新到8.0.0。

配置

Hexo在更新到5.0后，配置结构发生变化，NexT在8.0也有许多调整，因此选择转移原内容到一个新项目。将hexo-cli更新到最新版本再建立新项目：

1
2
3
npm update hexo-cli
hexo init blog
cd blog

然后查看package.json，确认Hexo版本在5.0以上。接着将配置文件.config.yml和原博客配置对比进行更新，并且将注意配置为NexT：

1
theme: next

接着安装NexT并将配置模板复制出来：

1
2
git clone https://github.com/next-theme/hexo-theme-next themes/next
cp themes/next/_config.yml _config.next.yml

参考NexT文档。这样NexT主题的配置内容只需要修改_config.next.yml文件即可，且未修改的配置条目可以直接删除。
之所以选择git方法而不是直接用npm安装主题，是因为如果主题修复了什么重要的issue，可以通过git及时应用修改，而不用等新版本发布。

其他依赖

下面是我用到的所有依赖，取自package.json：

1
2
3
4
5
6
7
8
9
10
11
12
13
"hexo": "^5.1.1",
"hexo-deployer-git": "^2.1.0",
"hexo-generator-archive": "^1.0.0",
"hexo-generator-category": "^1.0.0",
"hexo-generator-index": "^2.0.0",
"hexo-generator-searchdb": "^1.3.2", // local search
"hexo-generator-sitemap": "^2.1.0", // sitemap for google, baidu, ...
"hexo-generator-tag": "^1.0.0",
"hexo-renderer-ejs": "^1.0.0",
"hexo-renderer-markdown-it-plus": "^1.0.4", // for katex
"hexo-renderer-stylus": "^2.0.0",
"hexo-server": "^2.0.0",
"hexo-word-counter": "0.0.2" // word counter

指定HTTP协议

为了后面使用七牛云，网站选择使用http协议，但github也会默认开启https协议。为了让用户跳转回http协议，在script文件夹内新建redirect.js，输入

1
2
3
4
5
6
7
8
9
var srcjs = `<script>
if (window.location.protocol == 'https:') {
    window.location.href = "http"+window.location.href.substring(5);
}</script>
`;

hexo.extend.filter.register('theme_inject', function(injects) {
  injects.head.raw('redirect_protocol', srcjs, {}, {cache: true});
});

写作

首页摘要

在文章某处加入<!-- more -->，那么此处前边内容会成为摘要，如果点击“阅读全文”则会在打开文章后自动定位到此处。

插入图片

一般用CDN，但考虑到我们内容并不多，所以我选择和文章放在一起。把配置文件post_asset_folder改为true，这样新建文章的时候会在同目录下有个同名文件夹，把图片放到文件夹里面。使用以下命令来插入图片。

1
{% asset_img example.jpg This is an example image %}

插入公式

NexT对数学公式提供了需要时才加载JS的解决方案。修改主题配置文件，启用every_page，在需要数学公式的md文件的front-matter中加入mathjax: true即可。建议使用katex，那么除了把katex的enable打开之外，还需要以下操作：

1
2
npm uninstall hexo-renderer-marked
npm install hexo-renderer-markdown-it-plus --save

如果之前已经生成过文档，需要清空重来：

1
hexo clean && hexo g

站内引用

引用站内其他文章，可以使用绝对链接，也可以使用如下语法。

1
{% post_link 文章名 描述 %}

文章链接

文章链接默认是使用文章标题的，可能非常冗长，不好看，尤其是中文标题的文章。Hexo提供了一个Permalinks的功能，可以自定义文章的链接。新版本Hexo推出12字符长度的hash选项，文章数量不过万的话冲突概率极小，基本够用了。如果需要进一步缩短链接长度，可选方案：friendly-link, abbrlink2。

我的方案：修改node_modules/hexo/lib/plugins/filter/post_permalink.js文件，在变量meta中添加：

1
date_abbr: Math.floor((data.date.unix()-1377964800)/3600).toString(36)

这是因为我确认文章创建时间都在2013年9月1日之后，并且同一个小时内不会创建两篇文章。最后在.config.yml里配置

1
permalink: :date_abbr/

即可。方案与上面的可选方案一类似，但可选方案一无法正确解析文章内的资源文件路径。

外观

分类目录页面

参考Custom Pages。

404页面

需要自定义404的话，直接在source下新建404.md即可。设计404界面有两种方案，一种是把front-matter的layout设置为false，这样整个页面重新写过。第二种是我的方案，继承原主题风格，只要写内容就行。区别于普通文章，设置内容开头如下：

1
2
3
4
5
6
7
8
9
10
---
sitemap: false
comments: false
sidebar: false
toc:
  enable: false
---
<script type="text/javascript">
    document.title = "404 Not Found";
</script>

评论系统

多数评论系统不是被墙就是被关闭，目前还算好用的就是基于github issue设计的。我使用gitalk。

部署

代码双线路同时部署到github和七牛云上：境外访问的IP跳转github pages，而境内则使用七牛云，保证国内外访问都稳定和快速。为了七牛云使用方便，应使用http而不是https。

部署到github

在config中配置如下：

1
2
3
4
5
deploy:
  - type: git
    repo: 
      github: git@github.com:Aqua-Dream/aqua-dream.github.io.git
    branch: master

这样用hexo d可以自动更新文件到github仓库上。为了能自定义域名，在source文件夹下加入CNAME文件，内容仅一行，为自己的域名(aqua.hk.cn)。此外还需去github对应仓库上设置，在Custom domain中填入域名并保存。

部署到七牛云

先去下载qshell并放到hexo项目根目录下。在七牛账户的密钥管理中找到自己的密钥，然后命令行输入如下内容以添加账户：

1
qshell account ak sk name

在根目录内新建配置文件qupload.json并输入

1
2
3
4
5
6
{
  "src_dir": "public",
  "bucket": "aqua-blog",
  "overwrite" : true,
  "rescan_local" : true
}

最后在package.json里添加scripts

1
"publish": "hexo deploy && qshell qupload qupload.json"

使用npm run publish即可直接部署。本节参考将hexo博客一键部署到七牛云。

Sitemap

1
npm install hexo-generator-sitemap

在config最后新增

1
2
sitemap:
  path: sitemap.xml

提交sitemap前注意：部分页面不想被收录的需要在front-matter前加sitemap: false，比如404页面，比如站点确认文件等等。
此外在.config.yml中设置url: http://aqua.hk.cn，其中http不可以省略，否则对这里有影响。