参考官方指南

使用自定义 GitHub Actions 工作流进行发布
创建自定义 GitHub Actions 工作流以发布站点
GitHub Action: deploy-pages 🚀

TL;DR

将以下内容添加到现有的 Hexo 仓库中，在 GtiHub 仓库设置（/settings/pages）中将 Build and deployment > Source 选择为 GitHub Actions，最后 git push 即可。

.github/workflows/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
name: Deploy Hexo to GitHub Pages

on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - name: Checkout repository
      uses: actions/checkout@v4

    - name: Setup Node.js
      uses: actions/setup-node@v4
      with:
        node-version: '22.14.0'

    - name: Install dependencies
      run: npm install

    - name: Generate static files
      run: npm run build

    - name: Upload static files as artifact
      id: deployment
      uses: actions/upload-pages-artifact@v3
      with:
        path: public

  deploy:
    needs: build
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

问题引入

Hexo 的本地环境搭建和部署比较复杂，因此很多人选择了使用 GitHub Actions 自动部署 Hexo 博客，例如以下文章：

然而，这些文章一般将 Hexo 仓库和 GitHub Pages 仓库分开，通过 GitHub Actions 将静态页面部署到另一个仓库。这样做的好处是可以将 Hexo 仓库设置为私有仓库，而 GitHub Pages 仓库设置为公开仓库，这样可以保护 Hexo 源码。但是这样做有以下缺陷：

  • 在仓库列表观感上不够简洁，需要刻意区分源代码与部署产物。
  • 可能会占用 USERNAME.github.io 的仓库名，导致无法使用该仓库名作为其他用途。
  • 需要配置各种仓库的权限，需要配置 GitHub Token 等参数。
  • GitHub Actions 工作流比较复杂，涉及到调用 Git 的 config、commit、push --force 等操作，需要根据自己的实际仓库配置路径等。

事实上，GitHub Pages 不仅可以使用独立的仓库托管，也可以直接从 GitHub Actions 的构建产物（Artifact）中部署，无需各种鉴权参数。在本文所载的方法中，GitHub Actions 将源代码构建为 Artifact，再直接将 Artifact 部署到 GitHub Pages 中，从而不需要另外创建仓库。

逐步教程

1. 环境准备

本文假设您刚刚使用 hexo init 创建了一个 Hexo 本地项目：

shell
1
2
hexo init ExampleBlog
cd ExampleBlog

并初始化了一个 Git 仓库：

shell
1
git init

2. 创建 GitHub Actions 配置文件

在 Hexo 项目的 .github/workflows 目录下创建一个名为 deploy.yml 的文件，内容如下：

.github/workflows/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
name: Deploy Hexo to GitHub Pages

on:
  push:
    branches:
      - main # 仅在 main 分支 push 时触发

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - name: Checkout repository
      uses: actions/checkout@v4

    - name: Setup Node.js
      uses: actions/setup-node@v4
      with:
        node-version: '22.14.0'

    - name: Install dependencies
      run: npm install

    - name: Generate static files
      run: npm run build

    - name: Upload static files as artifact
      id: deployment
      uses: actions/upload-pages-artifact@v3
      with:
        path: public # 将 public 目录作为 Artifact 上传，这是 Hexo 默认的构建目录

  deploy:
    needs: build
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

有关以上工作流的详细说明，请参阅 GitHub 官方指南：创建自定义 GitHub Actions 工作流以发布站点

3. 配置 GitHub Pages

  1. 在 GitHub 网页，进入仓库的 Settings 页面。
    一张显示仓库头部标签页的截图，"Settings"（设置）标签页被红色边框高亮突出显示。
  2. 在左侧导航栏的 Code and automation 部分中，点击 Pages。
  3. 在 Build and deployment 部分的 Source 选择框中，选择 GitHub Actions。
    Build and deployment 设置中，将 Source 选项设置为 GitHub Actions
    Build and deployment 设置中，将 Source 选项设置为 GitHub Actions
  4. （可选）在 Custom domain 中设置自定义域名，详见 GitHub 官方文档：配置 GitHub Pages 站点的自定义域。

4. 提交并推送代码

1
2
3
git add .
git commit -m "First commit, with GitHub Actions"
git push origin main

5. 查看部署结果

在 GitHub 仓库的 Actions 页面查看工作流的执行情况，如果一切正常，您的 Hexo 博客应该已经部署到 GitHub Pages 上了。如果您之前没有为 GitHub Pages 配置自定义域名，您可以回到 Settings 页面的 Pages 部分查看和修改静态页面部署的网址。

在您的 GitHub 仓库的 Actions 页面中，可以查看工作流的运行结果
在您的 GitHub 仓库的 Actions 页面中，可以查看工作流的运行结果

优化部署速度

通过将 npm 换用为 yarn，并启用依赖缓存，可以大幅加快博客的构建速度，本博客实测的构建速度可从51秒缩短到26秒甚至更短。

注意，从 npm 迁移到 yarn 也需要在本地仓库进行一些更改，请参阅 Yarn 文档 了解如何使用 Yarn。

.github/workflows/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
name: Deploy Hexo to GitHub Pages

on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - name: Checkout repository
      uses: actions/checkout@v4

    - name: Setup Node.js
      uses: actions/setup-node@v4
      with:
        node-version: '22.14.0'
        cache: 'yarn'

    - name: Install dependencies
      run: yarn install --frozen-lockfile

    - name: Generate static files
      run: yarn run build

    - name: Upload static files as artifact
      id: deployment
      uses: actions/upload-pages-artifact@v3
      with:
        path: public

  deploy:
    needs: build
    permissions:
      pages: write
      id-token: write
    environment: 
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4
许可协议

本文采用 署名-非商业性使用-相同方式共享 4.0 国际 许可协议，转载请注明出处。