利用GitHub Actions+GitHub Pages自动部署Hexo博客

Abstract

将个人博客源文件托管到GitHub，利用GitHub Actions自动生成网页静态文件，利用GitHub Pages部署网站。

Keywords

GitHub Actions、GitHub Pages、Blog、Hexo

Introduction

GitHub Pages可以用来部署静态网站，其中有两种类型的GitHub repository可以用于部署网站：

  1. [your github name].github.io：如果是这种名字的repo，可以默认调用Github Pages来显示，该repo名字就是网址，可以直接访问，每个GitHub用户只能有一个这种repo；
  2. 普通的repo：如果是这种网站，需要在repo setting里手动打开Github Pages来生成网站，并且网站的名字比较长。

不过，二者都可以添加custom域名。

Methods

GitHub准备

建仓库

方便起见，我们可以建两个repo，一个是[your github name].github.io用来展示网页，一个是blog用来存放网页源代码。都建成private的！

获取GitHub令牌

可以通过GitHub令牌（Personal Access Tokens）来实现对repo的push。

步骤：GitHub Settings → Developer settings → Personal access tokens → Tokens(classic) → Generate new token → Generate new token(classic)→勾选必要的读写权限（不懂的可以都够上）→ Generate token

记得保存好这个令牌，它不会再次出现。

本地修改

博客部署

[your github name].github.io

在本地博客repo根目录下找到_config.yml，其中的deploy字段修改为：

1
2
3
4
deploy:
  type: git
  repo: git@github.com:/[你的GitHub名字]/[你的GitHub名字].github.io.git
  branch: main

然后尝试能否push到GitHub Pages：

1
hexo cl; hexo g; hexo d

博客托管

blog

1
2
3
4
5
git init # 新建 Git 仓库
git add -A  # 暂存所有文件
git commit -m "Create" # 提交更新
git remote add origin https://github.com/用户名/新建的私有仓库名.git # 新增远程链接
git push -u origin master # 推送至远程仓库

下面还需要其他修改，这里先配置，设置好remote repo，并尝试第一次push，验证是否能成功托管。

配置GitHub Action

1
2
mkdir -p .github/workflows/
touch .github/workflows/hexo_deploy.yml # 此yml名称随意

然后将下面代码自己修改一下之后写入hexo_deploy.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
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
# 如果想自定义solitude，那就自己fork一份，然后本地就安装自己的主题，然后再提交到自己的仓库
# 记得在.gitmodules文件里修改solitude主题的地址
# 
name: Deploy and Test # 部署 | 可以自定义
 
on: # 触发条件
  push:            # 当有代码推送到指定分支时触发工作流
    branches:
      - main       # 监视的分支名，或使用 '*' 匹配所有分支
  workflow_dispatch: # 手动触发，在 GitHub 仓库的 “Actions” 页面中，可以选择此工作流并手动点击运行按钮启动它。
 
jobs:
  build:
    runs-on: ubuntu-latest
 
    steps:
    - name: Checkout # Checkout(检出/下载) 仓库
      uses: actions/checkout@v3
      with:
        ref: main              # 希望检出（checkout）的是远程仓库的 main 分支
        submodules: recursive  # 克隆子模块! 子模块的分支在 .gitmodules 文件中指定，solitude设置的是main分支
        fetch-depth: 0         # 获取完整的 Git 历史，以避免子模块相关问题

    # - name: Verify solitude # 验证 solitude 主题
    #   run: |
    #     sudo apt-get install -y tree
    #     tree . # 如果solitude没有正确下载，是看不到themes/solitude/文件夹的
 
    - name: Setup Node # 安装 Node.js
      uses: actions/setup-node@v4
      with:
        node-version: "20.x"
 
    - name: Install Hexo # 安装 Hexo
      run: |
        # 如果已经在本地把solitude主题正确添加到外面项目的submodule里，就不需要再安装了！
        # rm -rf themes/solitude/ # 删除 solitude 主题，然后再安装
        # npm install hexo-theme-solitude --save  # 安装 solitude 主题

        npm install hexo-renderer-pug hexo-renderer-stylus --save  # 安装 Hexo 渲染插件
        npm install hexo-cli -g                                    # 安装 Hexo

        npm install hexo-abbrlink --save          # 安装 abbrlink 插件
        npm install hexo-generator-search --save  # 安装 本地搜索 插件
        npm install hexo-wordcount --save         # 安装 wordcount 插件

        npm un hexo-renderer-marked --save                     # katex｜如果有安装这个的话，卸载
        npm un hexo-renderer-kramed --save                     # katex｜如果有安装这个的话，卸载
        npm i hexo-renderer-markdown-it --save                 # katex｜需要安装这个渲染插件
        npm install katex @renbaoshuo/markdown-it-katex --save # katex｜需要安装这个katex插件
        
    - name: Cache Modules # 缓存 Node 插件
      uses: actions/cache@v4
      id: cache-modules
      with:
        path: node_modules
        key: ${{runner.OS}}-${{hashFiles('**/package-lock.json')}}
 
    - name: Install Dependencies # 如果没有缓存或 插件有更新，则安装插件
      if: steps.cache-modules.outputs.cache-hit != 'true'
      run: | # 如果仓库里没有 package-lock.json，上传一下，npm ci 必须要有 package-lock.json
        npm ci

    - name: Generate # 生成
      run: |
        hexo clean
        hexo generate
    - name: Deploy # 部署
      run: |
        git config --global user.name "你的GitHub名字"
        git config --global user.email "你的GitHub邮箱"
        export TZ='Asia/Shanghai'
        cd public/                   # public/里是生成的网页的全部静态文件，是需要部署到博客仓库的
        # echo "whb.baby" > CNAME # 自定义域名|可以用hexo将CNAME文件放到source文件中，就可以自动部署到public文件夹中
        git init
        git branch -m main # The just-created branch can be renamed via this command: git branch -m <name>
        git add -A
        git commit -m "Create by workflows"
        git remote add origin https://生成的令牌@github.com/你的GitHub名字/你的GitHub名字.github.io.git
        git push origin main -f # 本地分支:远程分支，-f是强制推送，必须要有，否则push不上去
        # git push origin main:main -f # 本地分支:远程分支，-f是强制推送，必须要有，否则push不上去
  • 其中的一些参数自己按自己的仓库需要进行修改！

添加submodule

为了方便GitHub Actions能checkout到托管到GitHub上的开源主题repo（如开源的主题：solitude），这里在本地repo中配置solitude主题为其submodule。下面的Install a submodule中的示例就是要使用的submodule添加命令。

Install a submodule
1
2
3
4
5
6
7
8
9
10
11
12
13
git submodule add -b <branch_name> <submodule_remote_url> <submodule_local_path> # 
git submodule update --init --recursive # 初始化和更新子模块
git add .gitmodules <submodule_local_path> # 将更改添加到 Git 的暂存区（staging area）
git commit -m "Add submodule <submodule_name>" # 提交暂存区内容
git submodule status # 验证

# 示例
# git clone -b main git@github.com:everfu/hexo-theme-solitude.git themes/solitude # 可以先clone再add，也可以直接add
git submodule add -b main git@github.com:everfu/hexo-theme-solitude.git themes/solitude
git submodule update --init --recursive
git add .gitmodules themes/solitude
git commit -m "Add submodule themes/solitude"
git submodule status
Delete a submodule
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
git submodule status # 或 git submodule | 显示当前子模块的状态
git submodule deinit <submodule_name> # 从Git配置中删除子模块的引用
rm -rf .git/modules/<submodule_name> # 删除子模块的内部Git配置
git rm --cached <submodule_name> # 把子模块从版本控制中移除
# 手动删除 .gitmodules 文件中的对应的记录
git add .
git commit -m "Remove submodule <submodule_name>" # 提交更改
rm -rf <submodule_name> # 如果不再需要子模块的文件，可以手动删除

# 示例
git submodule status
git submodule deinit themes/solitude
rm -rf .git/modules/themes/solitude
git rm --cached themes/solitude
# 手动删除 .gitmodules 文件中的对应的记录
git add .gitmodules
git commit -m "Remove submodule themes/solitude"
rm -rf themes/solitude

自定义域名

如果有需要的话，可以在GitHub Pages中添加自定义域名，添加之后会对国内访问速度有一定的提升。添加自定义域名的方式如下：

在 Hexo 项目的 source 目录下创建一个 CNAME 文件，内容为你的自定义域名，例如：yourdomain.com

每次 Hexo 生成静态文件时，source 目录中的文件会自动被复制到生成目录（默认是 public），因此 CNAME 文件会被保留在生成的 public 文件夹中。

需要注意的是，由于不论是hexo部署还是GitHub Actions部署，都是强制部署（push -f）的，因此如果仅仅在GitHub端手动修改，那么会将CNAME再次删掉。

开始执行

将本地repo push到GitHub上，并测试能否正常自动化生成并部署博客网站：

1
git push origin main

然后到对应GitHub Repo的Actions页面查看自动执行的结果。

发布博客

发布方式

发布方式一：每次写完博客之后，执行

1
2
3
git add -A
git commit -m "Update"
git push origin main

发布方式二：原来hexo的部署方式也能用，但是不会同步本地源代码到blog仓库

1
hexo cl; hexo g; hexo d

简化命令

可以利用shell脚本简化，例如：将下面的函数添加到.bashrc/.zshrc中。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# hexo
hexos() {hexo clean; hexo g; hexo s;} 
hexod() {hexo clean; hexo g; hexo d;}
# blog
blog() {code ~/Projects/blog/;}

# git
# 将所有更改（包括新增和删除的文件）添加到暂存区，提交并推送
gitpush() {
    echo ""
    echo "git add -A"
    echo "git commit -m \"${1:-"Quick commit"}\""
    echo "git push"
    echo ""
    git add -A
    git commit -m "${1:-"Quick commit"}"
    git push
}

Results

  • [你的名字].github.io 就是最后部署的网站
  • blog是网站的源代码

Conclusion

Recursive

原始教程中会把主题文件的git属性删掉，不过这样没有利用git的recursive挺可惜的。此方案还能将主题换成自定义的，只需要自己fork一下开源的主题repo，然后安装主题的时候装自己仓库的repo就好了。非常有利于后期自定义修改。而且有利于项目的分开管理。

References

网站部署

NPM包