背景

一直以来，我都是使用传统的本地部署方式来管理Hexo博客：

1
2
hexo generate
hexo deploy

每次写完文章后都需要手动执行这些命令，虽然不算麻烦，但总觉得不够现代化。最近终于下定决心，将博客部署流程自动化，使用GitHub Action实现”写完即发布”的效果。

需求分析

我的项目结构比较特殊：

  • 源码仓库：私有仓库，保存Hexo源码和配置文件
  • 静态网页仓库：公开仓库，专门用于GitHub Pages部署

目标很明确：修改源码后推送到私有仓库，自动触发GitHub Action，构建静态页面并部署到GitHub Pages。

配置过程

1. 权限设置

首先需要在私有仓库中配置GitHub Actions的权限：

  1. 进入私有仓库的Settings → Actions → General
  2. 找到”Workflow permissions”选项
  3. 选择”Read and write permissions”（读写权限）
  4. 保存设置

2. GitHub Action配置

创建.github/workflows/frontend-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: Frontend Hexo Deploy

on:
  push:
    paths:
      - 'source/**'
      - 'themes/**'
      - '_config.yml'
      - 'package.json'
    branches:
      - main

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          submodules: true
          fetch-depth: 0

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

      - name: Install dependencies
        run: npm install

      - name: Clean Hexo cache
        run: npm run clean

      - name: Build Hexo site
        run: npm run build

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public
          publish_branch: main
          external_repository: your-username/your-username.github.io
          cname: your-username.github.io
          force_orphan: true

3. SSH密钥配置

由于需要部署到外部仓库，我们使用SSH密钥方式进行认证，这是最可靠和安全的方式。

生成SSH密钥对

1
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

添加公钥到静态网页仓库

  1. 进入静态网页仓库 your-username/your-username.github.io
  2. 点击 Settings → Deploy keys
  3. 添加生成的公钥（~/.ssh/id_rsa.pub）
  4. 勾选 “Allow write access”

添加私钥到源码仓库Secrets

  1. 进入源码仓库 your-username/your-username.github.io.source
  2. 点击 Settings → Secrets and variables → Actions
  3. 添加新的Secret：
    • Name: DEPLOY_KEY
    • Value: 私钥内容（~/.ssh/id_rsa）

4. Hexo配置验证

确保_config.yml中的部署配置正确：

1
2
3
4
5
6
# Deployment
## Docs: https://hexo.io/docs/one-command-deployment
deploy:
  type: git
  repository: git@github.com:your-username/your-username.github.io.git
  branch: main

部署验证

1. 测试部署流程

完成配置后，我们可以通过以下步骤验证部署是否成功：

  1. 准备测试内容：对博客内容做一个微小的修改
  2. 推送测试提交：
    1
    2
    3
    git add .
    git commit -m "测试GitHub Action部署"
    git push origin main
  3. 查看Action运行状态：
    • 进入私有仓库的Actions页面
    • 查看刚刚触发的workflow运行记录
    • 检查每一步的运行状态

2. 验证部署结果

  1. 等待Action完成：通常需要1-2分钟
  2. 检查静态网页仓库：查看是否有新的提交
  3. 访问网站：打开GitHub Pages地址，验证修改是否生效

常见问题与解决方案

1. 跨仓库访问权限

问题：私有仓库的Action是否能访问到公开的静态网页仓库？

解答：是的，我们使用SSH密钥方式，只要在静态网页仓库中添加了对应的公钥，并在源码仓库中配置了私钥Secret，GitHub Action就能成功访问并部署到外部仓库。

2. 部署失败排查

如果部署失败，可以从以下几个方面排查：

  1. 查看详细日志：进入Action运行记录，查看每一步的输出
  2. 检查依赖安装：npm install是否成功
  3. 检查构建过程：hexo generate是否生成了静态文件
  4. 检查部署配置：外部仓库地址和分支是否正确
  5. 检查SSH密钥配置：
    • 公钥是否已添加到静态网页仓库
    • 私钥是否已正确添加到源码仓库的Secrets
    • Secret名称是否为DEPLOY_KEY
    • 公钥是否勾选了”Allow write access”

优势总结

相比传统的本地部署方式，GitHub Action自动部署具有以下优势：

  1. 自动化：无需手动执行部署命令，写完即发布
  2. 一致性：每次部署环境相同，减少部署差异
  3. 可追溯：每一次部署都有完整的日志记录
  4. 安全：无需在本地保存部署密钥
  5. 高效：节省手动部署的时间和精力

使用建议

  1. 合理设置触发条件：只在修改关键文件时触发部署
  2. 定期检查部署日志：确保部署流程正常运行
  3. 备份配置文件：将GitHub Action配置纳入版本控制
  4. 测试部署流程：新配置后进行测试，确保正常工作
  5. 关注GitHub Pages状态：定期访问网站，确保正常运行

结语

通过GitHub Action实现Hexo博客的自动部署，是一次现代化开发流程的实践。配置完成后，我只需要专注于创作内容，剩下的部署工作全部交给自动化流程处理。这种”写完即发布”的体验，让博客创作变得更加高效和愉悦。

如果你也在使用Hexo博客，不妨尝试配置GitHub Action自动部署，体验一下自动化带来的便利！