使用Github Actions部署Hexo博客

发表于 更新于

前言

作为技术博主，博客的高效维护与部署一直是我关注的重点。近期在维护博客时，我遇到了两个核心问题：

  1. 内容管理混乱：草稿箱文件堆积，缺乏分类标准，甚至因误操作破坏了原有配置；
  2. 兼容性局限：计划将文章同步至 FastGPT 等 AI 知识库时，发现官方推荐的 Hexo 部署方案（源码与静态文件混存）中，冗余的 public 目录会干扰 RAG 系统提取内容，且源码与发布产物耦合易引发冲突。

为解决这些问题，我采用了源码与发布分离的部署架构：将 Markdown 源文件单独存放在一个仓库，通过 GitHub Actions 自动在另一个仓库构建并发布静态文件。这种方式的优劣对比如下：

方案 优点 缺点
官方混仓部署 支持本地手动 / 自动发布，预览方便，配置简单 仓库体积大，源码与产物混合，不利于二次利用
本文分离部署 源码纯净、产物独立，兼容 AI 知识库，自动构建 本地预览需搭测试环境，配置较复杂（双仓库 + 鉴权）

部署核心思路

核心逻辑：当源码仓库收到推送时，GitHub Actions 自动将源文件检出到 source/_posts，并从 _hexo 目录复制配置文件还原 Hexo 环境，最终执行构建与发布。

文件结构设计（源码仓库）：

1
2
3
4
5
6
7
8
|-- _hexo/ # Hexo 核心配置目录 
| |-- _config.yml # Hexo 主配置 
| |-- _config.next.yml # NexT 主题配置 
| |-- package.json # Node 环境依赖 
| |-- scaffolds/ # 文章模板（draft/page/post.md） 
| |-- static/ # 静态资源（头像、支付码等） 
|-- .github/workflows/ # GitHub Actions 工作流配置 
|-- .obsidian/ # Obsidian 编辑器配置（可选）

详细部署步骤

1. 生成 SSH 密钥对（用于仓库间鉴权）

需要生成一对 SSH 密钥，用于源码仓库向发布仓库推送构建结果：

1
ssh-keygen -t rsa -C "<github 注册邮箱>"

执行后会在以下路径生成两个文件：

  • 私钥：~/.ssh/id_rsa（Linux/Mac）或 C:\Users\<用户名>\.ssh\id_rsa（Windows）
  • 公钥：~/.ssh/id_rsa.pub（同上路径）

注意：.ssh为隐藏目录，需要修改系统设置显示此文件夹

2. 准备两个仓库

仓库 1：源码仓库（存放 Markdown 与配置）

  • 新建仓库（例如命名为 hexo-source）
  • 进入仓库设置：Settings → Secrets and variables → Actions → New repository secret
  • 添加一个名为 HEXO_DEPLOY_KEY 的密钥，值为私钥 id_rsa 的内容（用记事本打开复制）

仓库 2：发布仓库（存放静态文件，用于 GitHub Pages）

  • 仓库名必须为 <你的 GitHub 用户名>.github.io（固定格式，否则 GitHub Pages 无法生效）
  • 权限需设为公开，并开启 Discussions 功能（进入仓库设置 → Features 勾选）
  • 配置部署密钥：Settings → Deploy keys → Add deploy key
    • Title 填 HEXO_DEPLOY_PUB
    • Key 填入公钥 id_rsa.pub 的内容，并勾选 Allow write access（允许推送权限）

3. 配置 Hexo 环境文件

在源码仓库中创建 _hexo 目录，放入以下核心文件（可从本地 Hexo 环境中复制, 参考Hexo-博客配置）：

  • _config.yml：Hexo 主配置（需修改部署相关配置，见步骤 4）
  • _config.next.yml：NexT 主题配置（其他主题同理）
  • package.json：依赖配置（需包含 hexo、hexo-deployer-git 等核心依赖）
  • scaffolds/：文章模板（draft.md/page.md/post.md）
  • 静态资源：如头像（avatar.jpg）、关于页（about.md）等，按实际需求存放

4. 配置部署与工作流文件

① Hexo 部署配置（_hexo/_config.yml）

在配置文件中添加部署规则，指向发布仓库：

1
2
3
4
5
6
7
8
# Deployment
## Docs: https://hexo.io/docs/deployment.html
deploy:
  - type: git
    repo: git@github.com:<username>/<username>.github.io.git
    branch: master
    name: <username>
    email: <email>

② GitHub Actions 工作流（.github/workflows/hexo-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
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
name: hexo-deploy  # 工作流名称

# 触发条件：向 master 分支推送时执行
on:
  push:
    branches: ["master"]
    
jobs:
  build:
    runs-on: ubuntu-latest  # 使用 Ubuntu 环境
    steps:
      # 1. 配置时区（避免时间显示异常）
      - name: Setup Timezone
        uses: szenius/set-timezone@v2.0
        with:
          timezoneLinux: "Asia/Shanghai"
      
      # 2. 拉取源码仓库内容到 source/_posts
      - uses: actions/checkout@v3
        with:
          path: source/_posts
      
      # 3. 安装 Node.js（需与本地开发环境版本一致，这里用 20.x）
      - name: Use Node.js 20
        uses: actions/setup-node@v4
        with:
          node-version: '20'
      
      # 4. 缓存 NPM 依赖（加速构建）
      - name: Cache NPM dependencies
        uses: actions/cache@v4
        with:
          path: node_modules
          key: ${{ runner.OS }}-npm-cache
          restore-keys: |
            ${{ runner.OS }}-npm-cache
      
      # 5. 配置 SSH 密钥（用于向发布仓库推送）
      - name: Setup Git
        env:
          ACTION_DEPLOY_KEY: ${{ secrets.HEXO_DEPLOY_KEY }}  # 引用源码仓库的私钥
        run: |
          mkdir -p ~/.ssh/
          echo "$ACTION_DEPLOY_KEY" > ~/.ssh/id_rsa
          chmod 700 ~/.ssh
          chmod 600 ~/.ssh/id_rsa  # 严格权限，否则 SSH 会拒绝使用
          ssh-keyscan github.com >> ~/.ssh/known_hosts  # 信任 GitHub 主机
      
      # 6. 拉取主题（以 NexT 为例，其他主题修改仓库地址即可）
      - name: Use Themes
        uses: actions/checkout@v3
        with:
          repository: next-theme/hexo-theme-next
          path: themes/next
      
      # 7. 还原 Hexo 环境（从 _hexo 目录复制配置文件）
      - name: Setup Hexo
        run: |
          npm install -g hexo-cli  # 全局安装 Hexo 命令行工具
          # 复制核心配置文件
          cp source/_posts/_hexo/_config.yml .
          cp source/_posts/_hexo/_config.next.yml .
          cp source/_posts/_hexo/package.json .
          # 复制文章模板
          mkdir scaffolds
          cp source/_posts/_hexo/scaffolds/* scaffolds/
          # 复制静态页面（关于页、分类页等，按实际需求调整）
          mkdir -p source/about source/categories source/tags source/images
          cp source/_posts/_hexo/about.md source/about/index.md
          cp source/_posts/_hexo/categories.md source/categories/index.md
          cp source/_posts/_hexo/tags.md source/tags/index.md
          cp source/_posts/_hexo/*.jpg source/images/  # 复制图片资源
          # 安装依赖
          npm install
      
      # 8. 缓存部署目录（加速后续构建）
      - name: Cache Deploy
        uses: actions/cache@v4
        with:
          path: .deploy_git
          key: ${{ runner.OS }}-deploy-cache
          restore-keys: |
            ${{ runner.OS }}-deploy-cache
      
      # 9. 构建并发布
      - name: Deploy
        run: |
          cd .deploy_git && git pull  # 拉取最新发布内容，避免冲突
          cd ..
          hexo clean  # 清理缓存
          hexo generate  # 生成静态文件
          hexo deploy  # 部署到发布仓库

验证与使用

  1. 将上述文件提交到源码仓库的 master 分支，GitHub Actions 会自动触发工作流；
  2. 进入源码仓库的 Actions 标签页，查看工作流执行状态，若显示绿色对勾则部署成功；
  3. 访问 https://<你的用户名>.github.io，即可看到最新发布的博客。

注意事项

  1. 私钥 HEXO_DEPLOY_KEY 是敏感信息，切勿泄露或提交到仓库；
  2. 发布仓库名必须严格为 <用户名>.github.io，否则 GitHub Pages 无法正常访问；
  3. 若主题是自定义修改过的，建议将主题 fork 到自己的仓库，再在工作流中拉取自己的 fork 版本；
  4. 本地预览时，可在源码仓库中手动搭建 Hexo 环境（复制 _hexo 目录文件，执行 hexo server）。

参考

Hexo官方提供的Github Actions部署示例