从本博客的建立谈 Github Actions 与 Github Pages 搭配构建静态博客

前言

开设一个属于自己的博客站点对许多人来说是一件相当具有吸引力的事情。我们在博客中可以编写并发表一些日记或者文章,同时还可以让别人也看到并发表评论,与自己进行讨论交流。在笔者看来,开设这样的博客可以满足我们编写文章、寻求知音的需要,同时也可以在一定程度上逼迫自己努力学习知识、丰富个人生活,编写更加精彩的文章。

开设一个个人博客有非常多种的办法。自从笔者在 2013 年搭建起自己的第一个博客以来,笔者听说过或者接触过的开设博客的方法包括:购买虚拟主机并使用 WordPress 或者 Typecho 等博客软件、直接使用博客园或者简书等现成的博客平台、搭建静态博客等。本文将向读者介绍其中的第三种方法——我们会使用 Hexo 这个静态博客生成器,同时结合 Github Actions 和 Github Pages 搭建一个能够自动构建和部署的个人博客。本文还会简单涉及腾讯云 CDN 的配置,使用 CDN 来加速博客的访问速度。

静态博客是什么

所谓静态博客,在笔者看来就是将编写的一篇篇文章直接转化为一个个.html 文件,放置在 HTTP 服务器上直接供人访问的博客。与 WordPress、Typecho 这样的“动态”博客不同,静态博客不需要利用数据库存储我们编写的文章,也不需要使用 PHP 等服务端语言去处理人们的访问,静态博客只是简单地将我们编写的文章转换为.html 文件,然后像 Nginx 这样的 HTTP 服务器会将这些.html 文件直接传输到人们的浏览器上,从而让人们能够看到我们的文章。

静态博客相比 WordPress、Typecho 等软件而言有着很多优势,例如上手难度低、配置简单、需要的资源很少。例如,要搭建一个基于 WordPress 的博客,我们往往需要花费金钱去购买一个提供数据库和 PHP 环境的虚拟主机,而对于一个静态博客而言,可以直接将生成的.html 文件部署到成本低很多的 HTTP 服务器上。

本文要介绍的 Hexo(https://hexo.io/) 是一个较为热门的静态博客生成器,它能够将我们编写的.md 文件(即使用 Markdown 编写的文章)转换为.html 文件,同时提供了丰富多彩的插件和主题来进行高度定制化。笔者还会介绍如何使用 Github 来让 Hexo 在.md 文件被更新时自动编译出最新的.html 文件,然后部署到 Github 提供的免费的 Http 服务器上,同时笔者还会介绍如何使用腾讯云 CDN 加速国内用户访问这些 Http 服务器。

基于这样的方法构建的博客不会花费我们一分钱,因为我们不需要购买任何主机或者服务,而且在全国范围内无论是电信还是联通用户都有相当好的访问速度。同时,与其他许多静态博客的维护相比,编写文章并发布到博客的流程相当容易,只需要编写.md 文件,然后 git push 即可,Github 会跑完接下来的编译、部署流程。

Github Pages 和 Github Actions

在实际进行博客构建之前,我们有必要先来了解一下什么是 Github Pages 和 Github Actions。

Github Pages 为我们提供了免费的静态资源托管服务,而且支持 HTTPS。简单地说,它就是一台免费的 HTTP 服务器,能够将我们上传的.html、.css 等文件传输到访问站点的用户的浏览器上。我们将 HTML、CSS 等文件通过 git push 到 Github 上的仓库之后就能用 https://xxx.github.io/ 这样的 url 提供给全世界各地的人们访问。

Github Actions 则复杂得多,不过对于这篇文章而言,我们只需要这样理解:它为我们的代码仓库提供了一套功能强大的 CI/CD 服务,能够自动为我们运行 Hexo 博客生成器。更简单地说,它就像是 Github 提供给你的服务器,你可以在上面运行各种程序。我们可以通过它来运行 Hexo,进而将我们编写的文章(主要是 .md 文件)编译为 .html.css.js 这样的静态资源,还能自动将这些文件部署到 Github Pages 对应的仓库上。

看到这里,读者应该明白了构建博客的思路:搭配使用 Github Actions 和 Github Pages,前者负责将我们编写的 .md 文件转换为静态文件,后者则向全世界提供这些静态文件的浏览服务。接下来我们正式开始介绍构建博客的一系列步骤,如果你有疑惑或任何意见,请在评论区中友善发言。

第一步:建立必要的 Github 仓库

这里,我们假设你的 Github 的用户名(username)是 xiaoming。你需要在 Github 上建立以下仓库:

  1. 名为 xiaoming.github.io 的仓库。这将是你的 Github Pages 服务所对应的仓库。仓库中所有文件将会被 Github Pages 的 Web 服务器托管,供人们用 https://xiaoming.github.io/ 这个 URL 访问,正如上文所说。请注意 Github 限制个人的顶级 Github Pages 仓库(也就是这个https://xiaoming.github.io/ 对应的仓库)只能托管 master 分支上的文件。

    然后,请打开这个仓库的 Settings 页面,向下滚动到 GitHub Pages 一节。确保 Source 被选为了 master,同时将 Enforce HTTPS 打开,这样 Github pages 就会强制人们用 https://xiaoming.github.io/去访问了。

  2. 储存 Hexo 博客的仓库,这里假设名为 blog,你可以取其他名字。这个仓库将托管你的 Hexo 博客生成器相关的文件,以及你编写的 .md 文章。Hexo 博客生成器的目录结构是这样的:

1
2
3
4
5
6
7
8
node_modules/      <- Hexo的依赖项
scaffolds/ <- 自动生成的文章的模板
themes/ <- 主题相关的文件
source/ <- 你编写的.md文章
public/ <- Hexo构建博客最终生成的静态文件
_config.yml <- Hexo的配置文件
package.json <- Hexo的依赖描述文件
package-lock.json <- 不用理解

建立完仓库之后,我们来配置 Hexo 吧。

第二步:配置 Hexo

首先你需要在你的电脑上安装 Node.js,我们要用它来运行 Hexo。请访问 Node.js 的官网 https://nodejs.org/en/,推荐下载左边按钮的 LTS 版本,它往往更加稳定。

然后你需要安装 Git,我们需要用它来将本地的文件上传到 Github 的仓库中。请访问 Git 官网的下载页 https://git-scm.com/downloads

安装成功之后,在电脑上找个地方运行以下命令(注意根据自己的情况替换 xiaomingblog,其中 blog 是我们刚刚建立的仓库的名字):

1
git clone https://github.com/xiaoming/blog.git

如果是 Windows 用户,你需要使用鼠标右键菜单中的 Open Git bash here 来打开能够运行 Git 的命令行。

运行成功之后,你应该会收到 Git 的类似于下面这样的提示:

1
WARNING: You've cloned an empty repository.

它告诉我们克隆了一个空的仓库,这符合我们的预期,因为我们刚刚建立的仓库应该就是什么也没有的。

然后我们运行以下命令(请忽略 # 号后面的内容):

1
2
3
4
npm install hexo-cli -g #安装Hexo
cd blog/ #切换到刚刚克隆下来的blog文件夹
hexo init . #初始化Hexo,不要漏掉这个点
npm install #安装Hexo的依赖

通过这些命令,我们成功在克隆下来的本地仓库中安装了 Hexo,让我们先给自己鼓鼓掌。

此时你已经可以参考 Hexo 官网上的文档 来配置自己的博客了。同时你可以在任何时候通过运行这个指令:

1
hexo server

来建立一个本地的 Web 服务器来向我们的浏览器展示 Hexo 编译产生的博客,你可以通过它来预览你的修改结果。注意:你应该在 blog 目录下运行这个命令,否则 Hexo 会提示你博客不存在。

你此时也可以开始配置自己博客的主题,以及编写文章,具体请参考上面的文档链接里的内容。如果遇到疑难,可以使用搜索引擎搜索相关内容。

在万事俱备后,我们可以在 blog 文件夹里运行以下命令:

1
2
3
git add .
git commit -m "你的修改信息"
git push

来将你配置好的 Hexo 相关文件上传到之前在 Github 上建立的 blog 仓库。如果你在 git push 上遇到了困难,你可能是因为自己没有给 Git 配置 Github 的用户信息,具体请你使用搜索引擎查找。

第三步:配置 Github Actions

由于我们需要让 Github Actions 在运行 Hexo 之后将 blog 仓库中的 public 文件夹发布到 xiaoming.github.io 仓库中供人们访问,因此 Github Actions 需要 xiaoming.github.io 仓库的 ACTIONS_DEPLOY_KEY,否则它没有权限去做这样的事情。

接下来我们访问 https://github.com/xiaoming/xiaoming.github.io/settings/keys(记得将 xiaoming 替换为你的 Github 用户名)。请参考官方给出的 这篇文章的片段 来配置 ACTIONS_DEPLOY_KEY

配置成功之后,打开 Github 上的 blog 仓库,选择 Actions 标签页,如下图所示,点击 New workflow 按钮。

然后,点击 set up a workflow yourself -> 文字,如下图所示:

然后,在左边的代码框中的所有代码删去,写上我准备好的以下代码:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
name: CI

on:
push:
branches: [master]
pull_request:
branches: [master]

jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2

- name: Setup Node.js environment
uses: actions/setup-node@v1.4.2
with:
node-version: 12

- name: Setup hexo
run: npm install

- name: Generate output
run: npx hexo generate

- name: Deploy
uses: peaceiris/actions-gh-pages@v3
with:
deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
external_repository: xiaoming/xiaoming.github.io
publish_branch: master
publish_dir: ./public

可以看到,这个文件描述了你的博客的构建过程,它选择最新版的 Ubuntu 作为基础,然后安装 Node.js,然后运行 npm install 来根据你的仓库中的 package.json 安装 Hexo 需要的依赖,之后就是运行 Hexo,产生输出,并将输出部署到 Github Pages 的仓库中。注意,请将最后几行中的 xiaoming 替换为你的 Github 用户名,其他不用改变。

然后,点击右上角的 Commit,向你的仓库中提交这个文件。之后,Github 就会在你通过 git push 向仓库推送修改(如修改配置、新增文章)时,自动为你运行 Hexo 进行博客的构建,并将产生的文件部署到 xiaoming.github.io 中,你就能通过 https://xiaoming.github.io/ 访问了!当然,别忘了在提交上面的文件之后,在你的本地仓库里运行 git pull 来将提交的文件更新到本地的仓库中,以免之后进行 git push 时发生冲突。

Github Actions 的一次成功的构建的例子,你其实可以在构建时实时查看控制台的输出

第四步(可选):配置个人域名和 CDN

如果你觉得 xiaoming.github.io 这个域名太过平凡,配不上自己的品味,那么我非常赞赏你的观点,因为我也是这种人(抬头看看浏览器地址框的 darkyzhou.net)。或许你也想来个 xiaoming.me 什么的域名指向上面创建的博客,可以吗?当然可以,Github Pages 早在几年前就全面支持了个人域名以及为个人域名提供 HTTPS 服务。

或许你会担心,如果购买域名会不会涉及到麻烦的备案流程。其实,如果你的域名是在国外的服务商购买的话,是完全不需要备案的,因为这个博客部署于 Github Pages 的服务器上,而直到目前为止,Github Pages 都没有在国内设置服务器,也就是说你的博客实际上是部署在国外的服务器上的。

然而,也正因为部署到国外服务器上,再加上国内特殊的网络环境,在很多情况下你的博客都会难以被国内的用户访问,有时甚至根本无法正常访问。此时你很可能需要一个国内的 CDN 去提高国内用户的访问速度。(关于 CDN 的知识这里略过,如果你不了解请使用搜索引擎搜索)。

然而,如果你选择在国外购买域名,你就很可能会在 CDN 上遇到困难,因为国内的大多数 CDN 都需要你为加速的域名备案,一旦域名需要备案,那么域名指向的博客网站也需要备案(我不太确定这两种备案是不是实际上是同一种备案)。如果你选择在国内的服务商购买域名,例如本博客的 darkyzhou.net 就是在腾讯云上购买的,那么你可以享受到国内的服务商给你提供的方便快捷的备案服务,以及免费但有限的国内 CDN 服务。因此,我建议你在国内的服务商购买域名,同时进行备案。其实,就腾讯云提供的备案服务来说,流程并不复杂,而且时间也相对较短(我从提交备案材料到备案通过只花了两周)。

当你购买好域名,备好案之后,我们进行以下步骤来让你的博客拥有自己的域名,以及国内 CDN 加速。假设你的域名是 xiaoming.me,使用腾讯云 CDN(其他 CDN 的步骤类似)。

首先,配置你的 CDN,在 腾讯云的 CDN 控制台的域名管理页 中,点击 添加域名 按钮,域名填写 xiaoming.me,其他配置如下图:

注意以下几点:

  1. 修改回源域名为你自己的域名。
  2. 源站地址的几个 IP 是 Github Pages 服务器的四个主要 IP,不直接使用 github.io 是因为可能会出现奇怪的问题。
  3. 缓存配置中的设置是我根据经验设置的,主要是为了确保首页和 Hexo 博客的文章页、归档页和标签页能够及时的刷新。你可以根据你使用的静态博客来设置响应的缓存配置。

然后,点击提交,待开通成功后,进入管理页的 Https配置,选择你的 HTTPS 证书。如果没有,可以去 腾讯云的 SSL 证书控制台xiaoming.me 申请一个免费证书。配置成功后,开启 HTTP 2.0,以及 强制跳转

与此同时,在域名控制台配置你的域名解析:

  1. xiaoming.me(主机记录 @)使用 CNAME 解析到你的 CDN 提供的加速地址,注意路线类型选择 境内
  2. xiaoming.me(主机记录 @)使用 CNAME 解析到 xiaoming.github.io,注意路线类型选择 境外
  3. www.xiaoming.me(主机记录 www)使用 CNAME 解析到你的 CDN 提供的加速地址,注意路线类型选择 境内
  4. www.xiaoming.me(主机记录 www)使用 CNAME 解析到 xiaoming.github.io,注意路线类型选择 境外

配置好后需要等待几小时来生效。

之后,打开 Github 向第三步中创建的 .github/workflow/main.yml 文件中末尾部分添加一行 cname: darkyzhou.net,如下面所示

1
2
3
4
5
6
7
8
- name: Deploy
uses: peaceiris/actions-gh-pages@v3
with:
deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
external_repository: xiaoming/xiaoming.github.io
publish_branch: master
publish_dir: ./public
cname: xiaoming.me

等待 Github Actions 重新构建,成功后,你应该可以在 xiaoming.github.io 的仓库的 Settings 页面的 Github Pages 一栏中看到 Custom Domain 被设置为了 xiaoming.me,如果没有请手动设置并应用。然后,选择 Enforce HTTPS,如果这个选项是灰色的,并提示出错,请稍等几小时,或者使用搜索引擎。

一切成功后,你的 Github Pages 一栏将如下图一样:

此时,打开浏览器,向地址框中输入 xiaoming.me,你将被导航到 https://xiaoming.me 并快速地加载出你的博客!

如果你想测试一下你的博客在开通 CDN 之后的访问速度在全国范围内究竟有没有提升,可以使用像 http://tool.chinaz.com/speedtest.aspx 这样的测速工具。下图是本博客的测速结果:

速度还算令人满意,不过据说又拍云的免费 CDN 有着更好的效果,或许将来有空可以试试。作为对比,请看看 darkyzhou.github.io 的测速结果:

测速结果非常不稳定,这次是绿下次就变成了橙甚至红。在国内没有 CDN,真是寸步难行呀。

下一步做什么?

通过以上步骤,你现在已经有个一个操作方便、访问快速的静态博客,接下来你应该去进一步做一些让你的博客变得更好的工作了,例如:

  1. 配置 SEO。合理运用 Google Search Console,以及百度资源平台,以及 Hexo 的 Sitemap 生成插件。
  2. 引入 Google Analytics(它的数据统计服务其实可以在国内访问,只是控制台不能)。它可以统计你的博客的访客信息,方便你了解你的博客的被访问情况,以及访客的喜好等。
  3. 培养一份责任感,维护好自己的博客,坚持持续编写文章。其实在我眼里,个人博客的地位相当于我们在广袤无垠的网络世界中的一个我们实际占据的角落,有了它,我们也相当于在网络世界中占据了一定的地位,显得不再那么虚无缥缈。这个博客不仅可以充当树洞,也可以发一些自己的技术文章。不必担心没有人看,因为总会有人看的,或者你并不追求有人能看你的博客,你只是希望充实自己在网络空间中的角落,充实自己的知识罢了。