Github Pages + Travis CI + Hexo 附 Hexo搭站小记

受到tangbao大佬博客(here)和其本人的启发和指导，也试了试用Github Pages + Hexo来搭博客。在这里记一个流水帐，希望能给需要的人提供一点帮助。

CI配置空降地址: TBD.

Warning: 本篇博客只面向计划用Github Pages + Hexo搭建博客的同学。

TODO

• FAQ
  • USERNAME.github.io 还是 其他Repo
  • 公仓还是私仓？
  • 自定义域名？
• 预先准备
  • Github账号
  • Node.js环境
  • Ruby环境
  • Git
• 建立Repo
  • 建立Repo
  • 设置Repo
    • .gitignore
    • .gitsubmodule
    • Deploy key
• 安装Hexo
  • 从npm安装Hexo
  • 初始化Hexo
  • 配置Hexo
    • CNAME
    • 基本配置
      • new_post_name
      • post_asset_folder
    • 主题 （暂时跳过）
      • scheme
      • disqus
      • social
    • 部署配置
      • branch: gh-pages
  • 第一次部署
• 配置CI
  • 在Github中安装Travis CI
  • 从gem安装travis
  • 登陆travis
  • 加密deploy key

FAQ

我需要会什么

• Markdown
• Git
• 会看文档
• 会安装环境

什么是Github Pages

参见这里。

公仓还是私仓？

目前无论公仓还是私仓均可生成公开的Github Pages。如果你不介意你的博客细节被公开，可以考虑使用公仓。反之可以考虑使用私仓。

自定义域名？

Github Pages提供一个以用户名作为三级域名的域名，其格式为USERNAME.github.io。（此处以根域左侧的为一级域名，以此类推。github.io为二级域名。USERNAME.github.io为三级域名）对于很多没有域名的同学来说，使用这样一个免费且相对好记的域名不失为一种很好的选择。缺点是对于一些不希望自己域名打开就是博客的同学来说，没法建立类似blog.USERNAME.github.io四级域名，只能使用USERNAME.github.io/blog这种格式。但是对于一个免费的三级域名，还要啥自行车呢？特别是对于部分只是想要一个博客网站同学来说，使用USERNAME.github.io作为博客地址不就足够了么。

对于有自己域名的同学来说，Github Pages支持自定义域名。这里的自由度就大很多了。请首先参见这里。简言之，你可以使用Github作为服务器托管你的博客，然后将域名指向USERNAME.github.io。

USERNAME.github.io 还是 其他Repo？

这个问题是接上一个问题的。对于没有自己域名的同学，如果使用USERNAME.github.io作为自己博客的地址，那么你需要建立名为USERNAME.github.io的repo。对于希望使用USERNAME.github.io/blog作为博客地址的同学，你需要建立名为blog的repo。以此类推，如果想以USERNAME.github.io/abc作为地址，需要建立的repo名为abc。

对于有自己域名的同学，请随意。

预先准备

Checklist

• Github账号
• Node.js环境 （For Hexo）
• Ruby环境 （For Travis Cli Client）
• Git

Github账号

相信看到这篇博客的都是有Github账号的同学。没有账号的可以在这里注册。Github目前只有英文版。建于本博客所建博客系统要用Markdown写作，英文不好的同学此处劝退。

Node.js环境

因为每个人使用的系统和平台并不一致，这里仅作简述。在安装时请注意权限问题。推荐使用node version manager来安装node。请不要尝试使用类似root或sudo之类的问题解决npm install -g安装时遇到的权限问题。使用node version manager将node.js安装在非系统目录可以解决这一问题。（以及请将node version manager安装在非系统目录。）可以参见这里。

Linux

在Linux下安时，包管理器会将node安装在系统目录\use\local\bin。这会引发上述问题。可以考虑使用n来安装node。参见这里。

On Linux and macOS, n-install allows installation directly from GitHub; for instance:

curl -L https://git.io/n-install | bash

n-install sets both PREFIX and N_PREFIX to $HOME/n, installs n to $HOME/n/bin, modifies the initialization files of supported shells to export N_PREFIX and add $HOME/n/bin to the PATH, and installs the latest LTS node version.

As a result, both n itself and all node versions it manages are hosted inside a single, optionally configurable directory, which you can later remove with the included n-uninstall script. n-update updates n itself to the latest version. See the n-install repo for more details.

https://github.com/tj/n#third-party-installers

Windows

在Windows下安装是我根据在Linux下安装的经验，直接选择了node version manager来进行管理和安装。同样注意安装时的权限问题即可。

在安装好node version manager之后，使用相对应的命令安装最新版的node即可。

(Optional) Ruby环境

因为安装Ruby是在安装Node.js之后，所以直接在Linux上直接使用了类似的版本管理器来进行安装。这里使用Windows的同学可以尝试按照官网对应的部分安装，或在安装Git后在Git Bash中按照Linux的方法安装。在Windows环境下我没有进行过测试，请小心前行。

这里Ruby环境是为了安装Travis客户端。对持续集成（CI）没有需求的同学可以跳过Ruby环境的安装。

Git

因为一直在使用Git，所以差点忘记了Git。

对于Linux用户，现在大多数发行版应该开箱即用的带了Git。对于Windows用户，请自行安装。macOS用户不是很确定，应该也是需要安装的。

安装过程很简单，基本保持默认设置即可。

建立Repo

建立Repo

登录Github后，点击右上角的加号图标来新建仓库。或者点击这里。

Repository name 填写仓库名称。可参见FAQ相关部分。对于想使用USERNAME.github.io作为地址的同学请填入USERNAME.github.io。想使用目录而非三级域名作为地址的同学请将期望的目录名作为仓库名称。拥有域名并且想使用自有域名的同学请随意起名。

Public or Private 选项同样参见FAQ。

其他保持默认设置即可，然后点击最下方的Create repository。

在建立repo后，会看到类似页面。

复制1中的链接，或者点2复制链接。（两者二选一）

然后打开终端（Linux或者macOS）或者Git Bash（Windows）。用cd命令切换到你中意的目录，你即将在工作目录下创建本地repo，所以请切换工作目录到你中意的目录。不懂请无视。

输入git clone，然后粘贴刚刚复制的地址。举例：git clone https://github.com/Frederick-Zhu/Frederick-Zhu.github.io.git。

设置repo

在搭建博客之前，还有一些准备工作。

.gitignore

我们并不想让所有的内容，特别是一些中间结果等，上传到Github。所以我们要设置.gitignore，使git命令忽视一些内容。

这里推荐https://gitignore.io。这个网站可以根据输入的关键词生成.gitignore文件。我们输入hexo和node。你也可以试着输入一下你的文本编辑器看有没有对应的内容。然后点击Create。

在repo文件夹中新建一个名为.gitignore的文本文件。并将生成的内容复制粘贴到.gitignore中。

然后在文件的开头，加入下面两行。

deploy_key
deploy_key.pub

.gitsubmodule

如同新建.gitignore文件一样，新建一个名为.gitmodules文件。不同的是，这里的文件不需要写入任何内容。

到这里，我们可以保存所有文件（目前为止，两个文件）。将他们加入git的缓冲区，并将它们提交，然后push到Github。相信各位同学都有这些基本知识。补课链接在这里。

(Optional) Deploy key

这个部分和持续集成有关，没有需求的同学可以跳过。

为了不把Github用户名密码泄露给持续集成系统，我们需要建立仓库对应的deploy key。deploy key的作用等效于用户名密码，有了这个key就可以操作repo。不同的是，这个key只能操作指定的repo（准确说是把这个key列为deploy key的repo）。即便泄露，也只有一个或几个repo收到影响。及时的在repo的设置中删除这个key就可以避免进一步的损失。所以建议请对每个repo分别建立deploy key。

基础知识在这里。

首先我们打开终端或者Git Bash，并将工作目录切换到repo的本地目录。然后开始生成密钥对。使用如下命令并将[email protected]替换为你的邮箱。

ssh-keygen -t rsa -b 4096 -C "[email protected]" -f deploy_key

你会看到如下的提示

Generating public/private rsa key pair.
Enter passphrase (empty for no passphrase):

这里直接回车，创建无密码的密钥对。

然后你会继续看到如下提示

Enter same passphrase again: 

同样的，直接回车。

你会看到本地repo文件夹下多了两个文件，分别名为deploy_key和deploy_key.pub。

注意：这两个文件均不要加入git缓冲区，或者提交到git，或者上传的Github。如果误操作，请删除这两个文件以及repo中的设置，并从头进行本节。

这也就是为什么上一步要在.gitignore文件中加入

deploy_key
deploy_key.pub

这两行的原因。

下面打开deploy_key.pub文件，你应该会看到两行。第一行很长，以ssh-rsa开头。第二行为空行，无内容。

打开Github。登录你的账户（如果你没有登录的话）。

官方指导在这里。从第二步开始，第一步生成密钥对已经完成了。

打开对应的repo，点击Settings，点击Deploy Keys，点击Add deploy key。把deploy_key.pub文件中第一行（以ssh-rsa开头的一行）复制粘贴进网页中Key下面的文本框。Title可留空不填，或根据个人喜好填写，这里不产生实质性区别。

勾选Allow write access。最后点击Add key。

你现在可以在Deploy keys页面看到你刚刚添加的公钥了。并且你的本地repo目录中现在有四个文件了。

安装Hexo

至此，我们可以开始准备安装hexo了。Hexo主页见这里。

根据官网给出的安装提示，我们可以轻松的完成安装。

这里有一点区别，因为我们先创建的repo，然而hexo需要在空文件夹中创建。所以我们要做的是新建一个文件夹，创建hexo，最后把所有内容复制粘贴（或者剪切）到本地repo目录。

从npm安装Hexo

在终端或者命令行（或者Power Shell）中运行下面的命令。

npm install hexo-cli -g

就是这么简单。

初始化Hexo

如上面所说的，首先建立一个新的目录。这里假设这么目录名为hexo。然后打开终端或者命令提示符，将工作目录切换到hexo的上级目录。

例如，hexo的位置为~/github/hexo，那么将工作目录切换到~/github。

然后执行。

hexo init hexo

打开hexo这个文件夹，将所有的内容复制粘贴到你的本地repo目录中。

再将终端或者命令提示符的工作目录切换到本地repo目录。执行下面的命令。

npm install

这样，hexo就已经初始化好了。

配置Hexo

但是此时的hexo还使用这默认配置，所以这一步，我们要更改一些基本的配置。

基本配置

关于配置文件，还是先推荐官方文档（这里）。

主要需要更改的内容：

• title: 自定
• author: 自定
• language: 推荐如下

  language: 
  - zh-Hans
  - zh-CN
  - en

• timezone: 自行设定
• url:
  这里填写你的域名，例如http://USERNAME.github.io，或者你自己的域名。如果想用http://USERNAME.github.io/blog这样地址的同学，这里请填写http://USERNAME.github.io，然后在root:后填写/blog。
• root:
  参见上一条，保持默认或按repo名称更改。
• new_post_name: 可根据喜好自行定制，个人使用如下。

  new_post_name: :year-:month-:day-:title.md # File name of new posts

• post_asset_folder: 推荐改为true

  post_asset_folder: true

CNAME

对于要使用自己域名的同学，请在source文件夹下建立一个名为CNAME的文件。内容为你要使用的域名。具体参见这里。

主题 （暂时跳过）

自行寻找喜欢的主题，并且根据主题的说明来安装吧。当然，不安装主题也是可以直接用默认主题的。

部署配置

这里配置hexo的部署功能。首先还是官方文档，在这里。

先安装hexo-deployer-git。在repo目录下执行：

npm install hexo-deployer-git --save

然后请根据上面的官方文档更改配置。（实在懒得写了，中文的官方文档写的很清楚了。）

这里把branch设定为gh-pages。

举例

deploy:
  type: git
  repo: <your repo link>
  branch: gh-pages

第一次部署

我们里目标已经很近了。保存所有的更改。将所有内容（除了deploy_key和deploy_key.pub之外）加入缓冲区，提交，并push到Github。

然后在本地repo目录执行

hexo g -d

然后稍等一下，你就可以在Github Pages中看到你刚刚建立好的博客了。

EOF