使用 Github 和 Hexo 快速搭建个人博客

作者简介：李科慧，腾讯高级工程师，天天 P 图 Android 开发。热爱生活，除了码代码以外，还喜欢旅游、阅读、游泳、绘画、手工、拼图，etc。

导语

个人兴趣爱好特别广泛，喜欢捣鼓各种小东西自娱自乐。虽然都没能深入研究，但是自己的“孩子”还是很想拿出来遛遛得人一句夸奖的。所以刚学 Markdown 的时候很是有想过要搭个个人博客来玩玩，一来激励自己练习 Markdown，二来也是展示一下自己的“劳动成果”。可惜第一次尝试 Github + Jeckyll 的搭配没能一次成功，忙起来了也就把这事儿放一边了。最近因为微信普通公众号不支持页面内插入多个链接（想做个集合贴链接到自己的不同作品），就又想着还是自己搭个网站吧。改变策略使用 Github + Hexo 倒是很快成功了，记录一下过程，如果能对其他想要搭建个人博客网站的小伙伴有帮助那就更好了。

0. 准备

Hexo 的官方文档挑重要的部分扫了一下，主要还是参考网上的一些帖子依样画的葫芦，遇到问题再去 Google 和度娘上找答案。问题也都不难解决，主要还是配置的问题，分享出来只是希望后来者可以少走点弯路。

首先说一下，Hexo 是一款基于 Node.js 的静态博客框架，支持 Markdown，符合大家需求的话就请听我慢慢道来。

我使用的是办公用的 Mac 来搭建的，本地的操作基本是用 Terminal 来完成的。其它操作系统应该类似，不过因为没验证尝试过也就不在这里谈到了。

我一共搭了两个博客，使用了不同的主题，一个比较简洁的，适合程序员发布技术贴；另一个是漂亮的 material design 风瀑布流，可以用来发布一些生活化的动态。因为 lz 有较为严重的整理癖，所以挑选的两个模板都有分类和 Tag 功能；同时也很想与同好们多多交流，并听听大家的反馈，所以找的都是有评论功能的主题（不过后一个的 disqus 第三方评论插件国内被墙啦~）。如果想要更简洁的、功能更强大的或者其他风格的模板，大家可以自行去 Hexo 的主题列表里挑选。

1. 注册 Github 账号

这一步对于工程师来说相信没啥难度，估计大家也都有账号了，需要注意的是：

• 要创建一个仓库（repo）和你的博客相关联。使用 Hexo 的话，对这个 repo 的名字是有要求的，必须是：your_github_username.github.com 格式。 也就是说，一个 Github 账号只能对应一个博客（其实 Hexo 配置文件里有一项是填写 Url 的，如果网站有子目录的话，可以填写子目录，所以猜测还是有希望在一个仓库里建立不同子目录来部署几个博客的，但是尝试了两次都没有成功后，我决定先采用不同的 Github 账号来配合不同的博客了）。
• 最好生成并配置 SSH Keys。也可以不配制，但不配置的话每次对自己的博客有改动要提交时，必须手动输入账号密码，配置了则不需要。我之前申请第一个账号时就已经配置好了，今天因为要使用一台电脑向两个 Github 账号发布内容，管理多个 SSH 秘钥比起新建一个需要更多费一点周折，就一并放在后文讲解了。

2. 安装 git，node.js 和 Hexo

• 安装命令行的 git，太久以前做的，具体已经忘了，应该就是去官网下载最新版并安装吧。它是用来把本地的 Hexo 内容提交到 Github 上，以及快速下载各主题的。
• 去 Node.js 官网下载最新版并安装；用于下载 Hexo 等工具和插件。
• 下载安装 Hexo：

$ npm install -g hexo-cli

3. 搭建博客

3.1 本地初始化博客

建立一个博客文件夹，文件夹的名称可以随意。建议不要选择需要管理员权限才能创建的目录。进入目录并初始化：

$ cd your_blog_dir
$ hexo init

使用 node.js 根据博客既定的 dependencies 配置安装所有的依赖包：

$ npm install

初始化博客以后，我们可以看到博客文件夹里多出了很多文件和目录。

3.2 根据需要配置博客

我们通过修改 _config.yml 文件来配置我们的博客。下面是我修改的几项参数信息（注意每一项的“:”后面都要保留一个空格）：

1) 填写网站相关信息

title: Choose a title
subtitle: Any subtitle you like
description: Anything you like
author: Your name
language: zh-CN
timezone: Asia/Shanghai

2) 配置个人域名

# URL
## If your site is put in a subdirectory, set url as 'http://yoursite.com/child' and root as '/child/'
url: http://yoursite.com/child
root: /

我的理解是，没有花钱购买了域名的话，可以不用填这两项。不过如果使用了评论系统，这两项必须正确填写。也许可以研究一下使用 root 的话是否就能用 Github 的一个 repository 搭建多个博客。我有尝试过配置 root 为 “/blog/”，但是把网站 deploy 以后，键入地址打开，会报找不到各资源（css，js等）的错，因为会去 /blog/ 下去寻找资源，而使用 Hexo deploy 我们的网站 的时候还是部署到仓库的根目录下的。不知道如果把网站部署到 Github 仓库的 /blog/ 目录下是否就可以了，目前还没有找到使用 Hexo 部署网站到 Github 子目录的方法。

3) 关联 Github 的部署信息 4)

deploy:
type: git
# 可以在 Github repository 首页的 `Clone or download` 按钮下找到下面的链接
repo: https://github.com/your_github_name/your_github_name.github.com.git
branch: master

3.3 部署博客

1）我们先进行本地发布，确认一下前面的操作是否都成功了：

$ hexo server

此时终端会输出：

INFO  Start processing
INFO  Hexo is running at http://localhost:4000/. Press Ctrl+C to stop.

打开浏览器，输入 http://localhost:4000/，应该就可以看到我们搭建好的博客和发布的文章了。

2）下载 Hexo 部署器，并将博客部署到网上：

注意，不执行下面第一行的话，可能会报 “ERROR Deployer not found: git” 或者 “ERROR Deployer not found: github” 的错

$ npm install hexo-deployer-git --save
$ hexo deploy

这时在 Github 的仓库里已经可以看见我们的网站目录和文件了。此时在浏览器地址栏键入我们的网址，即：your_github_name.github.io 就可以打开我们博客的主页了。

注意第一次打开估计需要做一些初始化的工作，会比较慢。

3.4 维护博客的一些常用操作

3.4.1 发布一篇博文

1) 在终端输入下列命令新建一篇文章：

$ hexo new "post_title"

就可以在本地博客文件夹的 /source/_post/ 目录下看到我们新建的 markdown 文件。

2) 用 Markdown 编辑器打开文件进行编辑，输入文章内容，保存后准备发布；

3）使用 Hexo 生成静态网页，并发布到网上： 每次我们更新了博客后，都需要让 Hexo 重新生成一下静态网页，可以在 public 目录的相应日期下看到生成的文件。（generate 可以缩写为 g，其它缩写见 Hexo 官方文档。）

$ hexo generate
$ hexo deploy

3.4.2 删除一篇博文

1) 去本地博客文件夹的 /source/_post/ 目录下删除需要删除的 .md 文件。

2) 去本地博客文件夹的 public 目录下删除该博文对应的文件夹（会按发布时间归到不同目录下）。

3) 在终端重新生成静态网页并发布：

$ hexo generate
$ hexo deploy

• 当我们更新博客时发生了任何问题，可以在终端输入下述命令清理并重新生成静态网页：

$ hexo clean
$ hexo g

3.4.3 博文首页展示长度控制

Hexo 博文在首页展示时，“Read More” 或 “阅读更多” 按钮出现的位置是由作者在写文章的时候设定的。只需在文章正文里合适的位置加上 <!-- more --> 此标记之前的正文内容就会成为该文章的简述，显示在首页里。

3.4.4 Hexo 中的 front-matter 配置

front-matter 是文件最上方分隔出来的一块 YAML 或 JSON 格式的区域。采用 YAML 格式书写时，Front-matter 以三个短横杠“---”同正文进行分隔，使用 JSON 格式时则是三个分号“;;;”。

front-matter 用于指定文章的一些属性，有：layout（布局），title（标题），date（文件建立日期），updated（文件更新日期），comments（文章评论功能开关），tags（标签（不适用于分页）），categories（分类（不适用于分页）），permalink 覆盖文章网址等。

下面介绍一下其中比较常用的几个：

1) title & date

在 hexo new 的时候会自动生成，当然也可以之后再编辑。

2) tags & categories

• 只有 post 类型的文件是支持 tags 和 categories 的。它们可以类似 java 数组的形式来表示，也可以分多行以短横杠开头来表示：

---
xxx: xxx
tags: [Github, Hexo, Blog, MathJax]
categories: 
- How To
- Hexo
- MathJax
---

如上填写完这两个属性，在 hexo g 的时候就会自动生成相应的标签和分类。如果所使用的 Hexo 主题的侧边栏有这两个模块，或者主题有相应的页面，就可以看到相应的生成结果被展示出来（下图是 Maupassant 主题自动生成的侧边栏 tags 和 categories 效果）。

• tags 和 categories 的最大区别是：当有多个并存时，categories 是顺序作用到 post 上、且有层级关系；而 tags 的各个元素是同一层级的，所以顺序并不重要。从上图貌似没有看出分类的层级效果，但是观察一下打开的 URL 就能发现不同了，同样是打开 “MathJax”，categories 的 URL 如下：

http://localhost:4000/categories/How-To/Hexo/MathJax/

tags 的则是：

http://localhost:4000/tags/MathJax/

• 如果您的分类有中文的话，譬如：categories: [美容, 护肤, 面膜]，那么您会发现，URL 里面也有中文：

http://localhost:4000/categories/美容/护肤/面膜/

复制黏贴出来的话，会更不友好：

http://localhost:4000/categories/%E7%BE%8E%E5%AE%B9/%E6%8A%A4%E8%82%A4/%E9%9D%A2%E8%86%9C/

想要让 URL 中尽量少出现中文，可以在博客的根目录配置文件 _config.yml 中利用 category_map 属性作映射。

category_map:
 美容: beauty
 护肤: skin care
 面膜: mask

如上配置后，得到的 url 就会变为：

http://localhost:4000/categories/beauty/skin-care/mask/

tag 也有相应的 tag_map。

3) toc

Hexo 默认不开启文章目录，若想要某篇文章根据标题权重自动生成目录显示在最右边，可以在 front-matter 中开启:

---
xxx: xxx
toc: true
---

从上图中可以看到，生成目录时会自动添加序号。所以如果使用自动生成的话，就无需再在文章中的标题添加序号了。

3.5 （可选）选择自己喜欢的主题

会写博客的小伙伴们估计还是比较重视细节和美观的，对博客的样式自然也有追求，简单说一下怎么替换主题，不同的主题替换起来略有不同，大家可以参考作者的指导。

Hexo 有两份主要的配置文件（文件名都是 _config.yml），一份位于站点根目录下的站点配置文件，另一份位于主题目录 themes 下的主题配置文件。

要安装一个新的 Hexo 主题一般分为两步：a. 将主题文件放置于站点的 themes 目录下；b. 修改配置文件。下面举一下我的两个例子：

3.5.1 Maupassant 主题在 Hexo 上的移植版

先上刚撘完时的效果图：

主要是看着作者的引导修改的，具体步骤如下：

1) 从 Github 上将主题下载下来，放到 /themes 目录下：

$ git clone https://github.com/tufu9441/maupassant-hexo.git themes/maupassant

2) 安装主题和渲染器：

$ npm install hexo-renderer-jade --save
$ npm install hexo-renderer-sass --save

3) 编辑博客目录下的 _config.yml 文件，将 theme 的值改为 maupassant。

4) 接着就是执行 clean，generate，deploy 三部曲了。

5) 还有很多可配置项，这里列举几项我尝试了的，其他的请参考作者的原文~

a. 按照默认配置，会有：“首页”、“归档”、“关于”、“订阅”四个 Tab，其中“首页”和“归档”是自动生成的，“关于”和“订阅”要生成一下，不然会找不到网页。

• 生成“关于”页面：

最简单的方法是：

$ hexo new page about

可以看见 source 目录下生成了 about 目录，此目录下的 index.md 文件就是“关于”页面了，大家可以根据自己的需要进行编辑。

想要添加其它页面，重复上述步骤即可。另一种生成页面的方法是： 在 source 目录下建立同所要生成的页面名字一样的文件夹，在其中创建 index.md 文件，并在 index.md 的 front-matter 中设置 layout 为 layout: page。若需要单栏页面，就将 layout 设置为 layout: single-column。

• 生成“订阅”页面：

首先要说明一下，由于生成 RSS 也就是订阅的插件同 Hexo 3.2 的兼容性的问题，我这边无法正常生成“订阅”页面，会报如下错误：

Error: Unable to call `the return value of (posts["first"])["updated"]["toISOString"]`, which is undefined or falsey

所以作为已经使用了 Hexo 3.2 的用户，我就只能把 RSS 从主页中移除啦~去主题的配置文件 _config.yml 中，将 menu 下的 RSS 配置注释掉：

menu:
  - page: home
    directory: .
    icon: fa-home
  - page: archive
    directory: archives/
    icon: fa-archive
  - page: about
    directory: about/
    icon: fa-user
  # - page: rss
  #   directory: atom.xml
  #   icon: fa-rss

其它功能模块也可用此种方式删除。

但是如果您装的是更早版本的 Hexo，是可以根据以下步骤自动生成 RSS 的： 安装两个插件：

$ npm install hexo-generator-feed --save
$ npm install hexo-generator-sitemap --save

在项目的 _config.xml 配置文件中添加这两个插件：

# 如果是 Hexo 3.2 及以上版本，无法使用 RSS 功能，必须将这两句注释掉，不然 generate 的时候会报错
plugins:
- hexo-generator-feed
- hexo-generator-sitemap

另外需要注意，项目的配置文件中的 URL 必须正确填写自己网站地址，不然 RSS 订阅不会成功。

b. 评论功能

对于我来说，评论功能还是很有用的，促进同好之间互相交流共同进步，这也是我写博客的最终目的吧~ Maupassant 主题是支持两大最常用的第三方评论的，disqus 和 多说。一般 disqus 国内加载会比较慢，但是会更稳定一点。因为我使用的网络环境连不上 disqus，所以也没什么好纠结的了，直接使用多说了。

• 首先去多说网站注册一下，一个账号对应于一个博客。
• 在主题的配置文件 _config.yml 中填上您刚刚注册得到的多说 shortname

duoshuo: <duoshuo_shortname>

• 之后就可以在文章和页面的 front-matter 中设置 comments: true 或 comments: false 来开启或关闭评论功能啦（默认开启）。

c. Maupassant 主题自动截取文章第一段作为摘要显示在首页，而不会显示全文。我们也能自定义摘要：

• 使用文章的 front-matter 中的 description 项来填写想要显示的摘要；
• 或者直接在正文内容中插入 <!--more-->，其前面的内容就会被认为是摘要。

d. 支持数学公式：

此主题已经集成了 MathJax 用于渲染 LaTeX 数学公式，按如下步骤可以打开：

• 要启用公式高亮，先在博客目录的 _config.yml 中添加：

mathjax: true

• 并在相应文章的 front-matter 中添加 mathjax 项来开启：

---
xxx: xxx
mathjax: true
---

对于行内公式，使用 $...$ 或 \\(...\\) 来标记；对于块级公式，默认定界符是 $$...$$ 和 \\[...\\]。

• 如果文章内容中出现美元符号“$”，而非行内公式的定界符，那么请在博客目录的 _config.yml 中添加：

mathjax2: true

相应地，在需要使用数学公式的文章的 front-matter 中也要使用 mathjax2: true。

3.5.2 Material 瀑布流效果的 material-flow 主题

可以先看一下作者博客的效果，而我刚撘完时的效果如下：

也是照着作者的引导来修改的，具体过程如下：

1) 从 Github 上下载主题到 /themes 目录下：

$ git clone https://github.com/stkevintan/hexo-theme-material-flow themes/material-flow

2) 下载依赖：

$ npm i -S hexo-generator-search hexo-generator-feed hexo-renderer-less hexo-autoprefixer hexo-generator-json-content

3) 编辑博客目录下的 _config.yml 文件，将 theme 的值改为 material-flow。

4) 将 avatar.jpg 和 favicon.ico 图片放到 /source/images/ 目录下，并在 _config.yml 文件中如下指定：

# Site
title: YOUR_TITLE
subtitle: YOUR_SUBTITLE
description: YOUR_DESC
keywords:
  - A_KEYWORD
  - A_KEYWORD
author: YOUR_NAME
avatar: /images/avatar.jpg  # the avatar image in the sidebar
favicon: /images/favicon.ico # the favicon
language: zh-CN
timezone: Asia/Shanghai

对于这个主题，此步骤不可省略，不然打开网站时会抛错。

• favicon 即 Favorites Icon，是地址栏网页标签最左侧的图标。有在线工具可以上传自己的图片去生成指定规格的 favicon.ico 文件。

5) 在 /source/_data/ 目录下建立并配置下述几个文件：

links.yml menu.yml widgets.yml

6) 在 /themes/material-flow/ 目录下按引导配置 _config.yml 文件。

7) 仍然是执行 clean，generate，deploy 三部曲了。

8) 其他可配置项：

a. 按照默认配置会有：“首页”、“归档”、“关于”三个 Tab，其中“首页”和“归档”是自动生成的，“关于”自行生成一下，具体事宜参见前文 Maupassant 主题的操作。

b. 评论功能

此 Material Flow 主题是支持 disqus 评论系统的，因为国内被墙，所以我也就没有配置了。

c. 此主题首页默认会显示文章全文，这会大大降低网站的加载速度，所以大家要记得配置每篇博文的摘要:

• 直接在正文内容中插入 <!--more-->，其前面的内容就会被认为是摘要。
• Material Flow 主题不支持在 front-matter 中的 description 项来标记摘要哦~

d. 支持数学公式：

此主题本身不支持数学公式，单纯靠自己人肉修改主题来支持数学公式还是比较麻烦的，幸而网上已有牛人开发了基于 MathJax 来渲染 LaTeX 数学公式的插件了，我们只要按文档安装配置就可以啦：

• 安装插件：

$ npm install hexo-math --save

• 初始化（虽然官网中有写此步骤，但实际操作时发现 Hexo 没有这个命令，且此步骤不必须。）

在博客文件夹中执行：

$ hexo math install

• 在主题目录的 _config.yml 中添加：（虽然官网中有写此步骤，但实际操作时发现无步骤亦可。） ``` plugins:
• hexo-math ```
• 然后就可以在你的文章中应用数学公式啦~~ 比起 Maupassant 主题自带的 MathJax，此插件的优点是： I) 无需在文章的 front-matter 中添加 MathJax 项来开启； II) 即使是首页摘要里的公式，也能正确显示；
• 不过使用过程中可能会因为 Markdown 与 LaTeX 的特殊字符冲突而产生一些小问题。

Hexo 会先用 marked.js 渲染 .md 文件，然后再交给 MathJax 渲染数学公式。譬如 LaTeX 中的换行符“\\”会先被 marked.js 转义成一个“\”，导致 MathJax 渲染时不认为它是换行了。针对个别字符二次转义的问题，我采取修改 marked.js 文件的方式来解决：

I) 用编辑器打开博客目录下的 /node_modules/marked/lib/marked.js 文件；

II) 将下述代码：

 escape: /^\\([\\`*{}\[\]()# +\-.!_>])/,

替换成:

escape: /^\\([`*\[\]()# +\-.!_>])/,

即取消了对“\\”，“\{”，“\}”等 LaTeX 特殊字符的转义。再配合 ASCII 码的 Unicode 来使用，perfect！

III) 注意这些修改要 clean 再 generate 才会生效哦~

4. 一台电脑上配置多个 SSH

因为博主之前已经在电脑上配置过 SSH 了，所以使用 Hexo 向 Github 部署时是不会要求输入账户密码的，这样就导致向第二个账号提交的时候自动使用了第一个账号的 SSH 从而失败。这里就说一下如何在一台电脑上，配置多个 Github 账号的 SSH，从而向多个 Hexo 博客发布博文。第一次新建 SSH 的情况也可以参照此方式来配置。

4.1 生成新的 SSH

Mac 下 SSH 是放在 ~/.ssh 目录下的。如果之前已经配置过 SSH，那么该目录下应该已存在一个 SSH 秘钥了，假设文件名为："github_rsa.pub"。在终端输入如下命令，用新账号生成新的秘钥，并根据提示输入用于保存的名字，如：“github_rsa_2”。

$ cd ~/.ssh
$ ssh-keygen -t rsa -C "yourSecondGithubEmail@email.com"
# Give your second ssh key another name: e.g., github_rsa_2
Generating public/private rsa key pair.
Enter file in which to save the key:
$ github_rsa_2

操作完成后，就可以看见目录下已经多了两个文件，github_rsa_2 和 github_rsa_2.pub。

4.2 将新的 SSH 秘钥添加到 SSH 代理中，以使你的电脑可以识别它：

$ ssh-add ~/.ssh/github_rsa_2

如果发生错误：“Could not open a connection to your authentication agent”，尝试下述命令：

$ ssh-agent bash
$ ssh-add ~/.ssh/github_rsa_2

4.3 配置管理你的多个 SSH 秘钥

1) 编辑 ~/.ssh 目录下的 config 文件，没有的话则新建一个。

$ cd ~/.ssh
$ touch config

2) 将下面的内容粘贴到 config 文件中：

# Default Github User
Host github.com
HostName github.com
User git
IdentityFile ~/.ssh/github_rsa

# Second Github User, the 'host' field will be used for Hexo deploying! Tried other name, not working.
# git2 is the alternative name of your second Github account, you can use it when you clone or update your project. Details can be found later.
Host git2    
HostName github.com
User git
IdentityFile ~/.ssh/github_rsa_2

4.4 关联 Github 账号

要将新生成的 github_rsa_2.pub 的内容添加到你的第二个 Github 账号中，从而可以使用它向 Github 提交内容。

1) 将 SSH 秘钥复制到剪贴板：

$ pbcopy < ~/.ssh/github_rsa_2.pub

如果 pbcopy 命令不起作用，可以直接去隐藏的 ~/.ssh 目录下用文字编辑器打开并复制其内容，小心不要加入多余的换行符或空格。

2) 进入 Github 网页的个人设置里，从侧边栏中进入 SSH and GPG keys，再点击 New SSH key 或 Add SSH key。

3) 在 Title 输入框中输入合适的名字来描述你的新秘钥，如："Office Mac - github_rsa_2"。

4) 将复制到剪贴板的秘钥粘贴至 Key 输入框中。

5) 点击 Add SSH key 并确认。

4.5 修改 Hexo 配置

打开你的第二个 Hexo 博客的 _config.yml 文件，并编辑如下：

# Deployment
deploy:
type: git
# 注意此处写法同之前的 'https' URL 的写法不同
repo: git2:2nd_github_account_name/2nd_github_account_name.github.io.git
branch: master

如果你还有其他 Github 账号，则可以重复上述步骤来继续添加。

总结

我搭建过程中遇到的各种情况基本都在前文讲述了，剩下的大家就自由发挥吧~

参考资料

[1] 代码咖啡. 20 分钟教你使用 hexo 搭建 github 博客，10/2016 [2] Jamie Paton. Setting up a Github Pages blog with Hexo，Nov. 2012 [3] 潘柏信. HEXO + Github，搭建属于自己的博客，08/2015 [4] 小道博客. hexo 博客更换主题，01/2016 [5] 屠夫9441. 大道至简—— Hexo 简洁主题推荐，11/2015 [6] Bryanyzhu. All about Hexo (4) - Publish Your Multiple Hexo Blogs with Multiple Github Accounts in One Computer，Dec. 2015