Hexo + Github page + Butterfly + Github Action搭建个人博客

Posted on | In | |

Hexo博客搭建
Hexo 博客利用 Github Action 自动化部署
利用 Github Actions 自动部署 Hexo 博客
hexo博客搭建从入门到入土完全优化系列
Github Pages+Hexo搭建博客

搭建流程

由于Github提供了免费的Page服务，所以就有了Hexo生成站点然后部署在Github Page上的玩法。博客的页面设计、部署等问题可以通过Hexo一键完成，作者只需要关注文章内容即可。本篇博文只对Windows操作系统的博客搭建过程进行记录，其他需求还请读者自行探索。搭建博客的整体思路是，首先使用Hexo一键生成博客站点，并使用butterfly对站点进行美化。然后，将站点部署到Github page上，即可通过访问[git_user_name].github.io来查看博客内容。接着，单独为博客内容创建一个仓库，使用Github Action监听内容仓库，如果内容仓库中有更新则重新将内容重新部署到博客当中。

Hexo

Hexo的安装方法可以直接参考Hexo官方文档，为保证博文结构完整性，将官方文档中的相应步骤抄录至本文中。

安装前提

在安装Hexo之前需要先安装下列应用程序：
Node.js (Node.js 版本需不低于 10.13，建议使用 Node.js 12.0 及以上版本)
Git
两者的安装过程中并无任何特殊配置，只需要点击“下一步”完成安装即可，读者可以根据自身喜好在安装过程中进行相应设置。安装完成后，可以在CMD中通过以下指定，测试是否安装成功。

1
2
3
$ node -v
$ npm -v
$ git -v

这里要记录一下node -v的结果，后续配置_config.yml时会使用到。
安装必备的应用程序后，需要创建一个空文件夹作为博客的项目路径，接下来我们将称这个创建好的文件夹为博客项目路径。进入博客项目路径，空白处点击右键，选择“Git Bash Here”，准备安装搭建博客所需要的工具。

安装Hexo

Hexo的安装方式相当简单。安装必备的应用程序后，使用 npm 指令安装即可，过程可能需要持续若干分钟。

1
$ npm install -g hexo-cli

安装完毕后，可以在CMD中使用hexo -v指令查看hexo版本以确定是否安装成功。

1
$ hexo -v

建站

安装阶段结束后开始建站，hexo可以使用init指令生成项目相关文件。

1
$ hexo init

执行完毕后，使用hexo s指令就可以在浏览器中输入“localhost:4000”访问博客，看到博客内容。

1
$ hexo s

Butterfly安装及配置

Butterfly的安装可以直接按照官方文档逐步进行。为保持博文结构完整性，同样将其中的内容摘抄过来，读者可能要注意命令的时效性。
首先，进入博客项目路径，呼出Git界面，输入以下命令。

1
git clone -b master https://github.com/jerryc127/hexo-theme-butterfly.git themes/butterfly

然后，将博客项目路径中的_config.yml中的[theme]对应的值修改为[butterfly]。
安装完成后可以在博客项目路径中看到butterfly文件夹，其中包含了主题的配置文件_config.yml，复制其中的内容，在博客项目路径中创建_config.butterfly.yml，将之前复制的内容粘贴后保存。
（使用过程中未能正确配置mathjax，无法渲染公式，所以最后放弃butterfly使用next主题）

部署

如果希望其他人也能看到你的博客，那就需要将博客部署在服务器或Github上。Github完全可以满足笔者对博客的需求，所以并未探索如何将博客部署在服务器上，读者有相关需求可以自行探索。

创建Github仓库

创建仓库需要读者已经创建过Github账户，这里不对如何注册Github账户进行赘述。拥有Github账户后，需要在本地配置账户信息。在任意位置唤出git bash，通过以下指令配置用户和邮箱。

1
2
$ git config --global user.name "你的名字"
$ git config --global user.email "你的@邮箱.com"

创建的仓库要求与Github用户名完全相同，并勾选“Add a README file”选项。

创建SSH和GPGkeys

在git bash命令窗口中输入命令生成SSH密钥，命令如下所示，注意-C是大写字母C，邮箱要加引号。

1
$ ssh-keygen -t rsa -C "你的@邮箱.com"

生成的内容可以在路径“C:\用户\用户名.ssh\id_rsa.pub”中查看到，将其中所有内容复制。
在Github中打开个人设置页面，左侧选中“SSH and GPG keys”，Title中的内容读者可以任意定义，在Key中粘贴刚刚复制的内容，然后点击“Add SSH key”。

开始部署

在博客的项目路径中唤出git bash窗口，安装部署工具，指令如下所示。

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

然后，在github中打开创建好的仓库，复制其git链接，如图所示。

然后修改博客项目路径中的“_config.yml”文件，在yml文件中，最下方可以看到“deploy:”，在其下方添加type、repo和branch，填写的内容如图所示。

推送至Github

使用clean指令清除缓存，然后使用g、d指令将博客内容推送至github，期间按照要求输入yes即可。

1
2
3
$ hexo c
$ hexo g
$ hexo d

执行完毕后，即可通过访问“[git_user_name].github.io”直接看到博客内容。
上述这种写博文、hexo clean、hexo g、hexo d更新博客的方式是hexo的基础用法。如果读者写博客的场景比较固定，不会涉及到多设备更新博客的话，hexo的基础用法已经足够满足需求了。但是如果写博文的设备并不固定，基础用法就不那么便利了。

配置Github Action

基础用法每次都会将本地的博文重新部署至github中，“删除文章”这一功能也是通过这种方式实现的，只要在本地删除博文后重新部署即可达到删除博文的目的。换句话说，如果在一个未保存全部博文的设备上更新内容，以往的心血就全被“删除”了。为避免上述情况出现，我们使用Github action来“备份”博客内容。首先，在Github中创建一个私有仓库，用于存储博客内容。然后，在本地编辑博文本，将新内容上传到博客内容仓库中，内容变动时触发Action，将新内容再部署到博客页面中。如果使用新设备撰写博客，只需要git clone博客内容仓库后编辑文本，重新push到仓库中即可。

创建存放博文内容的私有仓库

在创建过程中注意勾选private即可。

创建Token

访问 Github注意->右上角头像处->Settings->Developer Settings->Personal access tokens->generate new token,选择classic token即可，创建的 Token 名称随意，但必须勾选 repo 项 和 workflows 项。

创建好token后暂时不要关闭页面，这个token只在此处显示一次，关闭之后就无法找回Token内容。

配置Github Action

  1. 在本地的博客项目路径中创建[.github]文件夹，在其中创建[workflows]文件夹，在其中创建[autodeploy.yml]文件，其中内容如下：
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
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
name: 自动部署
# 当有改动推送到main分支时，启动Action
on:
  push:
    branches:
      - main
      #2020年10月后github新建仓库默认分支改为main，注意更改
  release:
    types:
      - published

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: 检查分支
        uses: actions/checkout@v2
        with:
          ref: main

      - name: 安装 Node
        uses: actions/setup-node@v1
        with:
          node-version: "16.x"

      - name: 安装 Hexo
        run: |
          export TZ='Asia/Shanghai'
          npm install hexo-cli -g

      - name: 缓存 Hexo
        id: cache-npm
        uses: actions/cache@v3
        env:
          cache-name: cache-node-modules
        with:
          path: node_modules
          key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ hashFiles('**/package-lock.json') }}
          restore-keys: |
            ${{ runner.os }}-build-${{ env.cache-name }}-
            ${{ runner.os }}-build-
            ${{ runner.os }}-

      - name: 安装依赖
        if: ${{ steps.cache-npm.outputs.cache-hit != 'true' }}
        run: |
          npm install --save

      - name: 生成静态文件
        run: |
          hexo clean
          hexo generate

      - name: 部署到Github
        uses: JamesIves/github-pages-deploy-action@v4
        with:
          token: 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
          repository-name: anzhiyu-a/anzhiyu-a.github.io
          branch: main
          folder: public
          commit-message: "${{ github.event.head_commit.message }} Updated By Github Actions"

ps:

  • 注意node.js的版本（node-version）与当前安装的版本一直
  • 如果配置完成后，push后workflow报错，请参考Github Action配置
  1. 在博客项目路径/themes/butterfly中的[.git]文件夹删除
  2. 在博客项目路径中呼出Git窗口，运行以下命令
1
2
3
4
5
git init #初始化
git remote add origin git@github.com:[GithubUsername]/[SourceRepo].git #复制刚创建好的博文内容私有仓库的git链接
git checkout -b main # 切换到main分支，
#2020年10月后github新建仓库默认分支改为main，注意更改
# 如果不是，后面的所有设置的分支记得保持一致
  1. 运行git提交指令，将博客源码提交到github上。
1
2
3
4
git add .
git commit -m "github action update"
git push origin main
#2020年10月后github新建仓库默认分支改为main，注意更改

总结

此时，博客更新的逻辑就变为，博客项目路径中的内容变动后，会提交至私有博文内容仓库中，内容仓库变动后Github Action会将内容重新部署到github.io仓库中。

如何使用？

想要撰写新博客时，打开博客项目路径，唤出git bash窗口，输入new指令创建md文件。

1
$ hexo new "博客名"

提示创建成功后，在生成的md文件中撰写文章，然后git add, git commmit, git push后，重新访问github.io页面即可看到更新内容。

小tips

1.post_asset_folder
当博文中需要引入图片等资源时，可以将_config.yml中的post_asset_folder参数设置为true。修改配置文件后，hexo new在创建md文件的同时还会为该博文创建一个同名的文件夹，用以存放博文中所需要的资源。要注意在博文中引入资源的方式，引入方法如图所示，使用传统的“叹号中括号括号”的引用方式是无效的。

图片未正常显示，先尝试删除Hexo-asset-image、Hexo-image-link等插件，按照官方文档逐步重新实现图片引用，还是不能正常渲染再参考其它博文。

查看网页原代码发现图片引用的位置全是.com文件：
图片显示bug参考
hexo-asset-image部分

hexo博客中插入图片失败——解决思路及个人最终解决办法

解决hexo-asset-image的图片地址错误问题

Notes on Hexo

hexo中完美插入本地图片

2.创建类别、标签
网上很多hexo创建类别的教程，笔者在最开始创建分类时陷入了一个误区，就是觉得要“先生成一个类别，然后在博文中才可以设置为这个类别”，其实不是。
实际上只要按照教程操作之后，你就可以任意的为你的博文添加类别了，hexo new page categories更“像是”允许作者为博文添加类别的开关。
3.引用历史博文
详见如何在Hexo的博文中引用自己的文章，要注意中间写的是文件名，不是博文title名。
4.博文分页
当按类别访问博文且该类别博文数量较多时，Hexo会根据博客数量进行分页，默认一页内摆放十篇博文，可以在_config.yml中的per_page属性进行修改。