GitHub Pages + Hexo + GitHub Actions 自动化建立博客网站

概述

本文网站：http://inaku-gyan.github.io

使用 Hexo 来解析文章，生成网页。

使用 GitHub Pages 托管网站，网站源代码储存在一个 GitHub 仓库里。

使用 GitHub Actions 自动化实现写作完成后用 Hexo 生成网页、用 GitHub Pages 部署的过程。

Hexo 提供了丰富的主题，本文使用了 Redefine 这一主题为例。

环境配置：Hexo 需要 Node.js 和 Git。

架构

A. 一个 GitHub 私有仓库。这个仓库由本地直接操作。包含：
- 工作流文件 .github/workflows/deploy.yml，GitHub Actions 将执行它完成自动任务。
- 网站相关配置（yaml 文件或 json 文件）
- 博文（markdown 文件）
- 图片等资源文件
B. 一个 GitHub 公共仓库，名字必须是 <username>.github.io（用户名中的大写字母要在仓库名中换为小写）。
- 存放网站的静态文件，即 html 网页、css 样式、js 脚本、字体、图片资源等。
- 通过 GitHub Pages 将仓库内容发布为网站。

流程

在本地完成网站内容的编写（即完成 A 仓库中的内容）
使用 Git 将本地的网站内容推送到 A 仓库的 main 分支
推送完成后，GitHub Actions 被自动触发执行 A 仓库中的 .github/workflows/deploy.yml 工作流：
1. 使用 Hexo 根据 A 仓库内容，创建 public/ 并在其下生成网站的静态文件；
2. 使用 Git 将 public/ 中的内容推送到 B 仓库。
GitHub Pages 自动将 B 仓库内容发布为网站。

建站、发布博文、更新网站等均通过上述流程。

建站并部署

建立 GitHub 仓库

私有仓库 A

新建一个空的私有仓库作为仓库 A，仓库名任取。

公共仓库 B

新建一个空的公共仓库作为仓库 B，仓库名为 <username>.github.io（用户名中的大写字母要在仓库名中换为小写）。

这样命名可以是网站地址为 https://<username>.github.io。

如果命名不遵循该格式，网站地址将是 https://<username>.github.io/<repo>

Token

仓库 A 中的工作流向 B 推送文件需要相应权限，我们用 GitHub 的 Personal Access Token 来给工作流赋权。

创建 Token

在 https://github.com/settings/tokens 中，生成一个新的 token (classic) 。填写 Note 备注一下该 token 的用处。

勾选 repo 权限即可。

复制生成的 token。

保存 Token

打开 A 仓库的设置，在 Secrets and variables / Actions 下，新建 repository secrete。

将刚才的 token 复制进去。

这里我把它命名为了 TOKEN_FOR_HEXO_DEPLOYMENT 。注意：之后在 workflow 的程序中会通过这个名字调用 token，如果你使用了其他名字，之后的工作流程序中也要进行更改。

环境配置

安装 Node.js 和 Git 。本处不提供 Git 相关初始配置及与 GitHub 进行 SSH 链接等的指导。

用 Node.js 的 npm 安装 Hexo：

npm install hexo-cli -g

安装初始资源

建立一个空文件夹，作为 Hexo 根目录。这个目录大体上就是 A 仓库的内容。

注意：之后的操作都在 Hexo 根目录中进行，之后的命令也都在 Hexo 根目录中执行。

初始化 Hexo

hexo init  # 初始化 Hexo
npm install  # 安装依赖

第二条指令会创建 node_modules 目录。

配置

填写 _config.yml 中的 url 项。例如：

# URL
## Set your site url here. For example, if you use GitHub Page, set url as 'https://username.github.io/project'
url: http://inaku-gyan.github.io

url 是建站完成后网站的地址。

初始化 Git

git init  # 初始化 Git
git remote add origin <A仓库的网址或SSH>  # 链接 A 仓库
git add -A
git commit -m "init"
git push -u origin main

默认情况下 public/ 不会被上传（也不该被上传），确保 .gitignore 文件中包含一行 public/。A 仓库的结构应该与示例储存库大致相似。

安装并配置主题

安装主题

使用 Git 安装 Redefine 主题：

git clone https://github.com/EvanNotFound/hexo-theme-redefine.git themes/redefine

主题被安装在了 themes/redefine/ 目录中。

删除 `.git` 目录

在 themes/redefine/ 目录下会存在一个隐藏的 .git 目录，把它删除！

否则， Hexo 根目录被推送到 A 仓库后， themes/redefine 会被 GitHub 判定为子模块，这将导致 GitHub Actions 中的 Hexo 无法打开 themes/redefine 而生成空白的网址静态文件。

更新主题

主题作者上传主题的新版本后，你可能需要更新主题。

更新主题的方法与安装主题的方法一样。每次更新主题后也要删除 .git 目录。

启用主题

在 Hexo 根目录的 _config.yml 文件中，将 theme 值修改为 redefine（或你使用的主题）。

theme: redefine

配置主题

在 Hexo 根目录手动新建一个主题配置文件 _config.redefine.yml，并将 themes/redefine/_config.yml 的内容全部复制进来。以后进行个性化的主题配置时，都在 _config.redefine.yml 中进行修改，而不改变 themes/redefine/_config.yml 的内容。

你可以删除原有的 _config.landscape.yml。

为什么这样做？

这样做可以避免每次升级主题后丢失之前的配置。

Hexo 主题是一个个独立项目，安装后它们以 themes/ 目录下一个个独立的文件夹的形式存在，并且每一个主题的文件夹中都有一个自己的 _config.yml 配置文件。升级主题就是用新版本的文件夹覆盖旧版本，这同时也会让原有的 _config.yml 被覆盖而丢失原来修改过的配置信息。

实际上 Hexo 提供了一个功能：自动合并 themes/[theme]/_config.yml 和 _config.[theme].yml 中的主题配置，并以后者为优先，生成最终的主题配置。“以后者为优先”可以简单理解为：若是两个配置文件中的共有项，则取 _config.[theme].yml 中的值；若是非共有项，则都加入最终的配置。于是我们借此来配置主题。

本地测试

完成到这里可以先进行一下本地测试。

hexo clean
hexo g
hexo s

然后根据命令行输出的相应提示，在浏览器访问对应地址，看一看你的网站在本地是否正常工作。

命令解释

`hexo g`

hexo generate 的简写，用于生成网站静态文件。实际效果就是在 Hexo 根目录生成了 public/ 和 db.json。

`hexo clean`

清除缓存文件 (db.json) 和已生成的静态文件 (public/) 。在某些情况（尤其是更换主题后），如果发现您对站点的更改无论如何也不生效，您可能需要运行该命令。

`hexo s`

hexo server 的简写，启动服务器。默认情况下，访问网址为： http://localhost:4000/。

工作流 workflow

手动新建目录及其下文件：.github/workflows/deploy.yml。

文件内容（请修改倒数第二排的相应内容）：

name: Deploy

on:
  push:
    branches:
      - main  # 当推送到 main 分支时触发

jobs:
  build:
    runs-on: ubuntu-latest  # 指定该程序运行所在的虚拟机

    steps:
      - name: 1. Checkout repository  # 检出 A 仓库的内容
        uses: actions/checkout@v4
        with:
          submodules: false # 禁用子模块

      - name: 2. Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'  # 用于指定使用的 Node.js 版本。建议使用与自己电脑中相同的版本，以避免可能的 IWOM 问题。

      - name: 3. Install Dependencies  # 安装依赖
        run: npm install

      - name: 4. Install Hexo  # 安装 Hexo
        run: npm install hexo-cli -g

      - name: 5. Clean and Generate Static Files
        run: |  # 用 Hexo 生成静态文件
          hexo clean
          hexo generate

      # - name: "Debug: tree"
      #   run: |  # 输出文件树
      #     tree -I node_modules -L 4 -h

      - name: 6. Configure Git
        run: git config --global user.name "auto deployer[bot]"

      - name: 7. Deploy to GitHub Pages
        run: |  # 使用 git 将 hexo 生成的 public 目录推送到使用 GitHub Pages 发布网页的公开仓库中
          cd public
          git init
          git add -A
          git commit -m "Created by workflows"
          git remote add origin https://${{ secrets.TOKEN_FOR_HEXO_DEPLOYMENT }}@github.com/inaku-Gyan/inaku-gyan.github.io.git 此处修改为你的 B 仓库地址
          git push origin HEAD:main -f

倒数第二排：以之前保存在 A 仓库 secrets 中的 token 为令牌，将 Git 链接到 B 仓库。

完成

将 Hexo 根目录推送到 A 仓库，建站。

git add -A
git commit -m "Added workflow"
git push

在 A 仓库的 Actions 中查看 workflow 运行情况。

在 B 仓库 Settings - Pages 中，做出如下设置：

Source 选择 Deploy from a branch
Branch 选择 main 和 /(root)

然后保存。

等待部署完成后即可访问网站。

inaku's Blog