利用 Github pages 和 hexo 搭建自己的博客

前言

Hello world!

这是我在新博客的第一篇博客文章，记录这个博客是如何搭建的。由于我并非专业人士，仅简略记录我的搭建过程和遇到的问题，并且不详细解释每一步的操作。如有疑问，请访问参考部分。

目前该博客处于美化阶段，主要内容为替换默认图片（背景，图标等）。博主艺术创作能力有限，欢迎提供帮助。

搭建博客

博客可以像搭建访问量较大的网站一样实现。一般来说，搭建网站需要购买服务器、域名、备案、购买云服务器等一系列繁琐的流程，如果要制作静态网页还需要自己手搓或者利用 WordPress 等 CMS 系统。而用 GitHub Pages 和 Hexo 搭建博客，可以快速搭建个人博客，而且不需要购买服务器、域名、备案等繁琐的流程。

Github Pages 是 Github 提供的静态页面托管服务，可以直接将静态网页托管到 Github Pages 仓库中，然后通过域名访问。相较于其他静态页面托管服务，Github Pages 免费、稳定、安全，但是在国内访问和加载资源较慢，适合个人博客。

理论上说，你完全可以自己手搓 HTML 页面和脚本完成博客。但对于像我这样的新手或者重点在成果而非过程的人来说，使用现成的框架和工具可以节省大量时间。Hexo 是一个基于 Node.js 的静态博客框架，它可以快速生成静态网页，并且可以用 Git 部署到 GitHub Pages。

创建 GitHub Page

登录 Github，创建一个名为 username.github.io 的仓库，其中 username 是你的 GitHub 用户名。这就是你的 GitHub Pages 站点的仓库。可以通过访问 https://username.github.io 来访问你站点的 index.html 文件。

安装配置 Git

从 Git 官网 下载安装。

因为 Git 是分布式版本控制系统，所以需要填写用户名和邮箱作为一个标识。在命令行输入：

1
2

git config --global user.name "user_name"   # user_name填入GitHub用户名
git config --global user.email "user_email" # user_email填入GitHub注册的邮箱

查看已设置的用户名和邮箱，在命令行输入：

1
2

git config user.name
git config user.email

配置 SSH key:

1

ssh-keygen -t rsa -C "user.email" # user.email为GitHub上注册的邮箱

三个默认设置就可以，不需要密码。在 C 盘 .../Users/your_user_name/.ssh 目录下找到 id_rsa.pub 公钥文件，复制里面的内容，在 GitHub_Settings_keys 上新建添加 SSH key。

输入以下命令检测是否配置成功：

1

ssh -T git@github.com

如果出现 Hi username! You've successfully authenticated, but GitHub does not provide shell access. 字样，则配置成功。

如果返回 Connection closed by 20.205.243.166 port 22，有可能是代理的问题。请关闭你的代理清除缓存（重启）并重试。

安装 Node.js

从 Node.js 官网 下载安装。

我用 Package Manager 安装 Node.js 遇到了问题，可选择使用 Prebuilt Installer 安装。

安装 Hexo

在命令行中输入以下命令安装 Hexo：

1

npm install -g hexo-cli

创建一个文件夹作为你的博客配置文件夹所在位置，并在其中打开命令行。输入

1
2
3

hexo init blog
cd blog
npm install

即可创建你的博客项目。其中 blog 是你的博客文件夹名。之后所有的操作都在 blog 文件夹中进行。

配置 Hexo

安装 hexo-deployer-git 插件，用于部署到 GitHub Pages。

1

npm install hexo-deployer-git --save

编辑根目录下的 _config.yml 文件，配置你的 deploy 部分站点信息。

1
2
3
4

deploy:
  type: git
  repository: git@github.com:StarCried/StarCried.github.io.git  #你的仓库地址
  branch: main

现在你已经搭建好了你的博客，可以进行本地预览和部署。

如果你本地预览正常而部署后静态资源未加载（比如主题格式混乱），请检查你的 _config.yml 文件中的 url 和 deploy 部分是否正确。

除了 deploy 部分，你还需要配置其他部分，包括 site 等。

使用 Hexo

Hexo 有以下常用命令：

1
2
3
4
5
6

hexo init     # 创建一个新的 Hexo 站点
hexo clean    # 清除缓存文件
hexo generate # 生成静态文件
hexo deploy   # 部署到 GitHub Pages
hexo server   # 启动本地预览服务器
hexo new <layout> <title>  # 创建新文章

Hexo 的工作流程是，在项目中进行主题配置（_config.yml 文件），用 hexo new 命令创建新文章、在 _posts 文件夹中编写文章后，运行 hexo generate 命令生成静态文件（要部署到 Github Pages 的文件，在 .deply_git 文件夹中），然后运行 hexo deploy 命令部署到 GitHub Pages。

美化博客

Hexo 官方提供了丰富的主题，你可以在 官方主题发布页 中查看。注意，大多数主题是由社区提供的，其配置方式和插件支持等千差万别，请根据自己的需求选择适合的主题。我是用的是 volantis 主题，阅读文档以自定义美化。

主题安装

参考 官方文档 安装主题。

主题文件夹下也有一个配置文件 /node_modules/hexo-theme-volantis/_config.yml。在博客根目录的 _config.yml 文件旁边新建一个文件 _config.volantis.yml ，这个文件中的配置信息优先级高于主题文件夹中的配置文件。将配置文件复制过来修改，以免配置丢失。

使用 npm 安装主题的配置文件在如上位置，而使用传统方式安装的主题配置文件在 theme 文件夹下。

遵循官方文档，修改配置文件 _config.volantis.yml 中的配置信息即可。

使用资源

在配置文件中，你可能经常看到图标使用 volantis-static 位置的图片资源。这是主题的官方静态资源库，可以直接使用里面的资源。

如果你想上传自己的资源，最简单的办法是使用图床或者另开一个 github 仓库，然后将图片链接替换到配置文件中。如果你觉得加载速度太慢，也可以使用 cdn 服务，参见文档。

密码插件

如果你想加密一些你的文章，使得只有正确输入密码之后才可以查看，那么你可以使用hexo-blog-encrypt 插件。

只需要按照文档安装和配置即可。不过每次上传文章前需要清除缓存。

数学公式

Hexo 自带 MathJax 插件，可以渲染数学公式。volantis 主题默认启用该插件，你只需要在每个用到数学公式的文章前的 front-matter 中添加 plugins: [mathjax] 就可以使用数学公式了。

使用的话，在文章中使用 $ 和 $$ 来包裹公式即可……吗？

对单行公式来说是这样的。但是对于多行公式，由于默认渲染器的原因（hexo-renderer-marked），会错误解读 // 优先为 Markdown 语法，导致渲染失败。（VScode 编辑器的 Markdown to PDF 插件也会遇到这个问题）

你可以根据官方文档选择自己喜欢的方式解决。

我解决的办法是更换渲染引擎。然而不同渲染引擎解决的方法不同，依然有可能遇到插件冲突问题。

比如，我第一次更换了 syzoj-renderer：

1
2

yarn remove hexo-renderer-marked
yarn add hexo-renderer-syzoj-renderer

如果你没有 yarn，可以安装一下（我没试过 npm）。

1

npm install --global yarn

它解决了多行渲染的问题。然而，这导致了标签插件没有正常被渲染。由于该插件有过和 Pjax 插件冲突的先例，怀疑是渲染逻辑的硬伤，于是更换了 pandoc：

1
2

yarn remove hexo-renderer-syzoj-renderer
npm install hexo-renderer-pandoc --save

同时，你还需要下载 pandoc 并将其导入环境变量或加入配置文件。

测试，解决了所有已知问题，并且浏览时右键公式可以复制源代码，十分方便。

图床

如果你想在博客中插入图片，那么你需要一个图床。将图片上传到图床后，你可以直接引用链接到博客里。

你可以直接将图片上传到博客仓库，然后引用，但 GitHub 的国内加载速度实在太慢。在多次试用之后，我找到了一个比较合适的图床网站：imagehub 图床，它免费、快速，但稳定性未知。

Live2D 插件

除了主题整合的可以直接使用的插件，你也可以自己装额外插件。在进阶玩法里有一个看板娘插件（实际是将 Live2D 模型渲染到页面上）。我想更进一步使用微光模型。然而模型还没影子

待更新。

转移博客

之前我主要使用的博客是博客园，需要将内容进行转移。参见 博客园 Cnblogs 迁移到 Github Pages。

参考

• GitHub-Hexo-从零开始搭建个人博客
• GitHub Pages + Hexo搭建个人博客网站，史上最全教程
• volantis 官方文档
• hexo 官方文档