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

導語

個人興趣愛好特別廣泛，喜歡搗鼓各種小東西自娛自樂。雖然都沒能深入研究，但是自己的“孩子”還是很想拿出來遛遛得人一句誇獎的。所以剛學 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 "[e-mail]" # 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