用 GitHub Actions 轻松实现 Hexo 博客自动发布

你是否也曾因为本地环境变动、重装系统等原因，导致博客的部署环境丢失，更新文章变得异常麻烦？写好的 Markdown 文件躺在文件夹里，却迟迟没有动力去配置环境发布。

今天，我们就来解决这个痛点！本文将带你一步步使用 GitHub Actions 来自动化部署你的 Hexo 博客。配置一次，之后你只需要专注于写作，写完 git push 一下，剩下的就交给 GitHub Actions 吧。

准备工作：两个代码仓库

在开始之前，我们需要准备两个 GitHub 仓库：

• 开发仓库 (dev)**：存放你的 Hexo 博客源代码，包括 Markdown 文章、主题文件、配置文件等。这个仓库通常设置为私有**。
• 部署仓库 (prd)**：用于存放 Hexo 生成的静态 HTML 页面。这个仓库必须是公开**的，并且仓库名需要是 <你的GitHub用户名>.github.io 的格式。

第一步：配置部署密钥

为了让 GitHub Actions 有权限从 dev 仓库拉取代码，并推送到 prd 仓库，我们需要设置一套 SSH 密钥。

1. 生成 SSH 密钥对

在你的本地电脑上打开终端，运行以下命令：

ssh-keygen -f github-deploy-key -N ""

这个命令会生成两个文件：github-deploy-key (私钥) 和 github-deploy-key.pub (公钥)。

2. 设置开发仓库 (dev) 的 Secret

我们需要将私钥告诉 dev 仓库，让它在运行时可以调用。

1. 进入你的 dev 仓库页面，点击 Settings → Secrets and variables → Actions。
2. 点击 New repository secret。
3. Name 填写 HEXO_DEPLOY_PRI。
4. Secret 粘贴 github-deploy-key 文件的全部内容。

3. 设置部署仓库 (prd) 的 Deploy Key

接着，我们需要让 prd 仓库认识我们的公钥，从而允许写入操作。

1. 进入你的 prd 仓库页面，点击 Settings → Deploy keys。
2. 点击 Add deploy key。
3. Title 随意填写，例如 HEXO_DEPLOY_PUB。
4. Key 粘贴 github-deploy-key.pub 文件的全部内容。
5. **勾选 Allow write access**，这一点非常重要！

第二步：修改 Hexo 部署配置

之前你可能是通过 HTTPS 来部署的，现在需要改成 SSH 方式。

打开你 dev 仓库中的 _config.yml 文件，找到 deploy 部分，修改 repo 字段为 SSH 地址。

# 原来可能是这样的:
# deploy:
#   type: git
#   repo: https://github.com/你的用户名/你的用户名.github.io.git
#   branch: master

# 现在请改成这样 (SSH地址):
deploy:
  type: git
  repo: [email protected]:你的用户名/你的用户名.github.io.git
  branch: master

提示：SSH 地址可以在你 prd 仓库的 Code 按钮下找到。

第三步：创建 GitHub Actions 配置文件

这是整个流程的核心。

1. 在你的 dev 仓库根目录下，创建一个 .github/workflows 文件夹。
2. 在该文件夹下，新建一个名为 deploy.yml 的文件。
3. 将下面的完整配置代码粘贴进去。

完整的 GitHub Actions 配置文件

# .github/workflows/deploy.yml

name: Deploy Hexo Blog

# 触发条件：当推送到 master 分支时运行
on:
  push:
    branches:
      - master # 这里改成你的源代码分支

jobs:
  build:
    # 运行环境：使用最新的 Ubuntu
    runs-on: ubuntu-latest
    strategy:
      matrix:
        # Node.js 版本：使用 20.x
        node-version: [20.x]

    steps:
      # 第一步：拉取 dev 仓库的源码
      - name: Checkout source code
        uses: actions/checkout@v4

      # 第二步：设置 Node.js 环境
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}

      # 第三步：配置部署环境
      - name: Configuration environment
        env:
          HEXO_DEPLOY_PRI: ${{ secrets.HEXO_DEPLOY_PRI }}
        run: |
          # 设置时区为上海，避免文章时间错乱
          sudo timedatectl set-timezone "Asia/Shanghai"
          
          # 配置SSH私钥
          mkdir -p ~/.ssh/
          echo "$HEXO_DEPLOY_PRI" | tr -d '\r' > ~/.ssh/id_rsa
          chmod 600 ~/.ssh/id_rsa
          ssh-keyscan github.com >> ~/.ssh/known_hosts
          
          # 配置 Git 用户信息
          git config --global user.name "your_username"
          git config --global user.email "[email protected]"

      # 第四步：安装依赖
      - name: Install dependencies
        run: |
          npm i -g hexo-cli
          npm ci # 使用 ci 可以确保依赖版本和 package-lock.json 一致
          # 如果你的主题有自己的依赖，也需要安装
          # cd themes/your-theme-name/
          # npm ci
          
      # 第五步：执行部署
      - name: Deploy Hexo
        run: |
          hexo clean
          hexo d -g

配置文件解析

• **on**：定义了触发条件。这里设置为每当 master 分支有 push 操作时，就会自动运行。
• **jobs**：定义了要执行的任务。
• **runs-on**：指定了运行任务的虚拟机环境，这里是 ubuntu-latest。
• **steps**：任务的具体步骤。
  • actions/checkout@v4：官方提供的 Action，用于拉取你的仓库代码。
  • actions/setup-node@v4：官方提供的 Action，用于安装和配置 Node.js 环境。
  • Configuration environment：这个步骤是自定义的，核心是：
    1. 设置时区，防止因为服务器时区不同导致文章发布日期错误。
    2. 从我们之前设置的 Secrets 中读取私钥，并配置好 SSH 环境。
    3. 设置 Git 的用户名和邮箱。
  • Install dependencies：安装 Hexo 命令行工具和项目依赖。使用 npm ci 比 npm i 更快、更稳定，因为它会严格按照 package-lock.json 来安装。
  • Deploy hexo：执行 Hexo 的标准部署命令，清除缓存、生成静态文件并部署。

第四步：测试

现在，一切都准备就绪了！你可以尝试修改一篇博文，或者新建一篇文章，然后将改动 git push 到你的 dev 仓库的 master 分支。

推送完成后，打开 dev 仓库的 Actions 标签页，你会看到一个新的工作流正在运行。你可以点进去查看详细的日志。如果一切顺利，几分钟后，你的博客网站就会更新！

常见问题排查 (Q&A)

Q1: Action 运行成功了，但是打开网站是空白的？

A: 这通常是 Node.js 版本和 Hexo 或其插件版本不兼容导致的。我遇到的情况是本地 Node.js 版本较低，而 Action 中使用了较新的 Node.js 20.x。

解决方案：升级你项目中的 Hexo 版本。

1. 在本地运行 hexo init temp-blog 创建一个临时的最新版 Hexo 项目。
2. 对比新项目中的 package.json和你自己项目的 package.json，将 dependencies 和 devDependencies 中的版本号更新到较新的版本。
3. 删除 node_modules 和 package-lock.json，然后运行 npm install 重新安装依赖。
4. 在本地测试 hexo g 能否成功生成页面，确认无误后再提交。

Q2: 部署后，自定义域名失效了，CNAME 文件变成空的了？

A: 这个问题比较玄学。按照 Hexo 的官方文档，CNAME、ads.txt 等自定义文件应该放在 dev 仓库的 source 文件夹下。但在某些情况下，它们可能不会被正确地复制到部署目录。

解决方案：尝试将 CNAME 这类文件也复制一份到你所使用主题的 source 目录下。例如 themes/your-theme/source/CNAME。虽然原理不明，但这个方法解决了我的问题。

---

至此，你的 Hexo 博客自动化部署流程就全部完成了。现在，你可以彻底告别繁琐的本地部署步骤，随时随地，只要能 git push，就能更新你的博客。快去享受纯粹的写作乐趣吧！