在 GitHub Actions 上部署 Hexo 博客

发表于 更新于 分类于 本文字数： 1.5k 阅读时长 ≈ 15 分钟

参考资料：

本文将使用 GitHub Actions 部署至 GitHub Pages，
此方法适用于公开或私人储存库。

使用 Hexo 创建第一篇博客

1
2
3
hexo: 7.2.0
hexo-cli: 4.3.2
node: 21.7.1

开始

项目初始化

指定文件夹初始化，新建hexo项目

1
2
3
$ hexo init <folder>
$ cd <folder>
$ npm install

执行完成后，目录结构如下

1
2
3
4
5
6
7
8
.
├── _config.yml					# hexo 配置文件
├── package.json				# hexo 依赖文件
├── scaffolds					# 模版目录
├── source
|   ├── _drafts					# 归档目录
|   └── _posts					# 博客目录
└── themes					# 主题目录

对于各个文件、目录更多详情，请移步 Hexo官方文档：建站

新建第一篇博客

1
2
# 如果没有设置 layout 的话，默认 post
$ hexo new [layout] --path [path/title] "title"

更多命令，请移步 Hexo官方文档：指令

本地运行 hexo

1
2
3
$ hexo server
# 或者
$ npm run server

执行命令，当看到截图所示，则说明项目启动成功 🎉

使用 GitHub Actions 部署 Hexo 博客

GitHub Actions 是一种持续集成和持续交付(CI/CD) 平台，
可用于自动执行生成、测试和部署管道。

GitHub Pages 是一项静态站点托管服务，它直接从GitHub 上的仓库获取HTML、
CSS 和JavaScript 文件，（可选）通过构建过程运行文件，然后发布网站。

所以，我们需要两个github repository：

  1. blog 仓库用于存放hexo源码
  2. maozzi.github.io 仓库用于存放hexo 打包编译后的静态文件

设计两个repo的原因：

  1. 代码不会互相干扰，源代码更加简洁，不会增加多余的静态文件
  2. 源代码库可以选择private，更高的安全性、隐私性

开始

新建两个仓库，blog（名字随意）与 maozzi.github.io，blog仓库公开(public)还是私有(private)
自行决定，影响不大。

⚠️注意：
maozzi.github.io 仓库名字比较特殊，跟 GitHub Pages 规则有关。就是
只有命名以 {github的username}.github.io 项目名称格式，最终才能通过
https://{github的username}.github.io 访问自己的博客。

我的 {github的username} 是 maozzi，所以我的项目名为 maozzi.github.io，
同时可以通过 https://maozzi.github.io 访问我的博客。

基本配置

我们主要往源代码库(blog)推送hexo项目代码，blog 仓库执行打包编译，
那么 blog 仓库如何把打包后代码推送给 maozzi.github.io 呢？

这时需要使用 git push 命令：

1
git push --force https://{token}@github.com/{username}/{username}.github.io.git master:master

这条命令需要两个参数：

  1. token: 指 github 生成的具有选定权限的密钥 token
  2. username: 指 GitHub username，就是你的登录用户名，不是昵称！！！

token 配置

  1. 进入 github 个人设置(Settings)，URL: https://github.com/settings/profile
  2. 往下滑，找到 Developer Settings 进入，URL：https://github.com/settings/apps
  3. 展开 Personal access tokens，选择 Tokens (classic) 点击进入，
    选择右上角 Generate new token -> classic， URL：https://github.com/settings/tokens
  4. 最后，选择想要的权限，点击完成，保存好这个token，可以选择永不过期，
    URL：https://github.com/settings/tokens/new

blog 仓库配置

blog 仓库，主要工作是使用 GitHub Actions 打包编译hexo项目，最后把打包好的静态文件
git push 到 maozzi.github.io 仓库。

GitHub Actions 每次打包编译都是新建一个新的docker 容器环境，所有的工作都是在
docker 容器中完成。在最后的 git push 需要使用到的参数，则需要使用环境变量，
而环境变量，则需要 blog 仓库来设置。

  1. 进入 blog 仓库设置(Settings)
  2. 选择 Secrets and variables -> actions，点击 New repository secret
  3. 新建3个环境变量
    1. DEPLOY_KEY：刚才生成的 github token，用于 git push
    2. EMAIL：github 注册邮箱，用于在docker容器中git全局邮箱设置
    3. USERNAME：github 登录用户名，用于在docker容器中git全局用户名设置以及
      git push 需使用

GitHub Actions 脚本文件

GitHub Actions 以工作流方式，使其在存储库中发生事件（例如打开拉取请求或创建问题）时触发。

工作流包含一个或多个可按顺序或并行运行的作业。工作流程由签入到存储库的 YAML 文件定义，
并在存储库中的事件触发时运行，也可以手动触发，或按定义的时间表触发。

每个作业都将在其自己的虚拟机运行器中或在容器中运行，并具有一个或多个步骤，
用于运行定义的脚本或运行动作。

动作是一个可重用的扩展，可简化工作流。

定义工作流(定义 YAML 文件)

在hexo项目中，新建 .github/workflows/deploy.yml，yaml文件名可以随意

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
name: Deploy

on:
  push:
    branches:
      - master

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          submodules: true # Checkout private submodules(themes or something else).

      - name: Use Node.js 21
        uses: actions/setup-node@v4
        with:
          # Examples: 20, 18.19, >=16.20.2, lts/Iron, lts/Hydrogen, *, latest, current, node
          # Ref: https://github.com/actions/setup-node#supported-version-syntax
          node-version: "21"

      - name: Cache NPM dependencies
        uses: actions/cache@v4
        with:
          path: node_modules
          key: ${{runner.OS}}-${{hashFiles('**/package-lock.json')}}
          restore-keys: |
            ${{ runner.OS }}-npm-cache

      - name: Install Dependencies
        if: steps.cache.outputs.cache-hit != 'true'
        run: |
          npm install
          npm run build

      - name: Upload Pages artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./public

      # Deploy hexo blog website.
      - name: Deploy
        id: deploy
        run: |
          cd ./public
          git init
          git config --global user.name '${{ secrets.USERNAME }}'
          git config --global user.email '${{ secrets.EMAIL }}'
          git add .
          git commit -m "${{ github.event.head_commit.message }} $(date +"%Z %Y-%m-%d %A %H:%M:%S") Updated By Github Actions"
          git push --force https://${{ secrets.DEPLOY_KEY }}@github.com/${{ secrets.USERNAME }}/${{ secrets.USERNAME }}.github.io.git master:master

本地推送代码

blog 仓库是保存源代码的，保存 hexo 项目，所以本地 git push 代码到 blog 仓库即可。

1
git push origin master

验证

进入 blog 仓库 -> Actions，查看工作流的状态：

  1. 工作流如果绿勾✅，则说明运行成功，可以查看 maozzi.github.io 仓库是否有文件，
    https://maozzi.github.io，是否可以访问
  2. 工作流如果红叉❌，则说明运行失败，点击进入详情查看失败原因，逐步分析。

遇到的问题

  1. Q：node 版本问题 
    1
    notsup Unsupported engine for hexo-log@4.1.0: wanted: {"node":">=14"} (current: {"node":"12.22.12","npm":"6.14.16"})
    A：修改或指定yaml文件中node版本
  2. Q：npm ci 问题

    A：改成npm i