Hexo 静态博客方案 ｜ GitHub Actions 自动化部署

[!abstract] 适用环境与目标

• 适用环境：macOS / Windows / Linux + Node.js 16.0+ + Git
• 目标：在 GitHub Pages 上搭建 Hexo 静态博客，实现「写文章 → 推送源码 → 自动构建并部署」的全自动化工作流

概述

静态博客方案结合了 Markdown 的写作体验和 GitHub Pages 的免费托管能力，是个人技术博客和知识库的首选方案之一。Hexo 作为最流行的静态博客框架，生态成熟、主题丰富、部署方式灵活，社区中积累了大量开箱即用的主题和插件。

本文以一个真实的生产环境博客（伞间岁月）为案例，详细讲解：

• Hexo 项目的初始化和核心配置
• 主题选择与定制要点
• GitHub Actions 自动化部署流水线的完整搭建
• 自定义域名与 CDN 加速
• 日常写作工作流和问题排查

一、整体架构

静态博客方案的核心思想是 源码与静态文件分离：源码仓库存放 Hexo 源文件（Markdown 文章、主题、配置），GitHub Pages 仓库只存放构建后的 HTML/CSS/JS。两者通过 GitHub Actions 自动同步。

                  Hexo 源码仓库
          github.com/你的用户名/blog-source

_posts/        themes/        _config.yml     .github/
文章.md        主题文件         package         workflows/
                              .json           deploy.yml
                    │ git push (main 分支)
                    ▼

                  GitHub Actions

1. actions/checkout@v3 → 拉取源码
2. 安装 Node.js + npm ci
3. hexo generate → 构建静态文件
4. 推送 public/ 到 Pages 仓库的 gh-pages 分支

                    │ 自动部署
                    ▼

                 GitHub Pages 仓库
      github.com/你的用户名/你的用户名.github.io

gh-pages 分支：index.html, archives/, posts/, ...

                    │ GitHub Pages 服务
                    ▼
                  https://你的域名/

这种架构的优势：

• 职责清晰：源文件和构建产物互不干扰
• 安全可控：源码仓库可设为 Private，Pages 仓库保持 Public
• 零成本运维：GitHub Pages + Actions 的免费额度对个人博客绰绰有余
• 全自动化：一次配置，永久生效，只管写作和推送

二、前置准备

2.1 安装 Node.js

Hexo 基于 Node.js，首先确保系统已安装 Node.js 16.0+：

# macOS
brew install node

# Windows（推荐使用 nvm-windows 或直接下载安装包）
# https://nodejs.org/

# Linux
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# 验证版本
node -v
npm -v

2.2 安装 Git 并配置 SSH

# macOS
brew install git

# Windows: https://git-scm.com/download/win
# Linux: sudo apt-get install git

# 配置全局身份信息
git config --global user.name "你的 GitHub 用户名"
git config --global user.email "你的邮箱@example.com"

# 生成 SSH 密钥对
ssh-keygen -t ed25519 -C "你的邮箱@example.com"

# 查看并复制公钥
cat ~/.ssh/id_ed25519.pub

将输出的公钥添加到 GitHub → Settings → SSH and GPG keys → New SSH key。

[!tip] SSH 配置参考
SSH 的详细配置（包括多账号、权限问题排查）可参考同系列的 《微信小程序 Git 远程仓库设置》。

2.3 创建两个 GitHub 仓库

需要准备两个仓库：

[!info] 命名说明
如果你的站点是用户级 Pages（https://你的用户名.github.io），Pages 仓库必须命名为 你的用户名.github.io。如果是项目级 Pages（https://你的用户名.github.io/仓库名/），仓库名可以任意。

三、初始化 Hexo 项目

3.1 安装 Hexo CLI

npm install -g hexo-cli

3.2 创建项目

# 在目标目录创建 Hexo 项目
hexo init blog-source
cd blog-source

# 安装项目依赖
npm install

hexo init 生成的目录结构：

blog-source/
├── _config.yml        # 站点配置文件——最重要的配置文件
├── package.json       # Node.js 依赖声明
├── node_modules/      # 依赖包（不提交到 Git）
├── scaffolds/         # 文章模板（可自定义）
├── source/            # 源文件目录
│   ├── _posts/        # 博客文章（Markdown 文件）
│   └── CNAME          # 自定义域名文件（可选）
├── themes/            # 主题目录
└── public/            # 构建输出（自动生成，不提交）

3.3 安装常用插件

npm install hexo-abbrlink hexo-generator-feed --save

各插件作用：

四、站点配置

4.1 编辑 _config.yml

项目根目录的 _config.yml 是 Hexo 的核心配置文件。以下是关键配置项：

# ===== 站点信息 =====
title: 我的博客
subtitle: '副标题'
description: '博客描述，用于 SEO'
author: 你的名字
language: zh-CN
timezone: ''

# ===== URL 配置 =====
url: https://你的域名.com                         # 博客最终访问地址
permalink: posts/:abbrlink/                       # 使用 abbrlink 短链接
permalink_defaults:
pretty_urls:
  trailing_index: false                           # 去除 index.html

# ===== 目录配置 =====
source_dir: source
public_dir: public
tag_dir: tags
archive_dir: archives
category_dir: categories

# ===== 写作配置 =====
syntax_highlighter: false       # 关闭内置高亮（交给主题处理）
highlight:
  enable: false
prismjs:
  enable: false

# ===== 首页分页 =====
index_generator:
  per_page: 10
  order_by: -date

# ===== 文章短链接（hexo-abbrlink）=====
abbrlink:
  alg: crc32                    # 算法：crc16（更短）或 crc32（更唯一）
  reps: true                    # 使用数字 + 字母混合

# ===== RSS Feed =====
feed:
  type: atom
  path: atom.xml
  limit: 20
  order_by: -date

4.2 初始化 Git 并推送到远程

git init
git add .
git commit -m "feat: init hexo blog"

git remote add origin git@github.com:你的用户名/blog-source.git
git branch -M main
git push -u origin main

五、主题配置

5.1 选择主题

Hexo 拥有丰富的主题生态，可通过 Hexo Themes 官方列表 浏览。以下是社区中活跃度较高的主题：

5.2 安装主题

以 Keep 主题为例：

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

在 _config.yml 中启用：

theme: keep

5.3 主题配置方式（重要）

每个主题都有自己的配置项，有两种配置方式：

方式一（推荐）：在项目根目录创建 _config.{主题名}.yml，Hexo 会自动合并此文件的内容到主题默认配置之上。这样做的好处是避免直接修改 themes/ 目录下的文件，方便以后升级主题。

# _config.keep.yml
menu:
  首页: /
  归档: /archives/
  分类: /categories/
  标签: /tags/

favicon: /images/favicon.png
avatar: /images/avatar.jpg

social:
  GitHub: https://github.com/你的用户名

方式二：直接编辑 themes/keep/_config.yml（不推荐，升级主题时会覆盖）。

[!note] 主题渲染器依赖
部分主题需要额外的渲染器。Keep 主题需要 hexo-renderer-ejs 和 hexo-renderer-stylus，Butterfly 需要 hexo-renderer-pug。安装主题时请阅读其文档确认。

六、GitHub Actions 自动化部署

这是本方案的核心环节。配置完成后，你只需要 git push 源码，博客便会自动构建并部署。

6.1 部署流程概览

你写文章 → git push → GitHub Actions 触发 →
  → Checkout 源码 → 安装依赖 → hexo generate →
  → 推送 public/ 到 Pages 仓库 → GitHub Pages 生效

6.2 创建 GitHub Personal Access Token

GitHub Actions 需要权限将构建产物推送到 Pages 仓库：

1. 打开 GitHub → 右上角头像 → Settings → Developer settings → Personal access tokens → Tokens (classic)
2. 点击 Generate new token (classic)
3. Note：填写 HEXO_DEPLOY（方便识别）
4. Expiration：选择 No expiration（永不过期），或选择 90 天并在过期前刷新
5. Scopes：勾选 repo（Full control of private repositories）——这包含了将文件推送到仓库所需的所有权限
6. 点击底部的 Generate token
7. 立即复制并保存生成的 Token（关闭页面后将无法再次查看）

6.3 将 Token 添加到源码仓库 Secrets

1. 打开你的源码仓库 → Settings → Secrets and variables → Actions
2. 点击 New repository secret
3. Name：HEXO_DEPLOY（必须与 workflow 文件中引用的名称一致）
4. Secret：粘贴上一步保存的 Token
5. 点击 Add secret

6.4 创建 Workflow 文件

在项目根目录创建 .github/workflows/hexo-deploy.yml：

name: deploying Hexo project to GitHub pages
on:
  push:
    branches:
      - main  # 当 main 分支有推送时触发

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

      - name: Build and Deploy
        uses: theme-keep/hexo-deploy-github-pages-action@master
        env:
          PERSONAL_TOKEN: ${{ secrets.HEXO_DEPLOY }}
          PUBLISH_REPOSITORY: 你的用户名/你的Pages仓库名
          BRANCH: gh-pages
          PUBLISH_DIR: ./public

关键配置项说明：

这个 Action 会自动完成以下步骤：

1. 拉取源码仓库的最新代码
2. 安装 Node.js（内置使用 Node 18）
3. 执行 npm ci 安装依赖（比 npm install 更快，且保证依赖版本锁定）
4. 执行 npx hexo generate 构建静态文件
5. 将 public/ 目录下的所有文件推送到 Pages 仓库的 gh-pages 分支
6. gh-pages 分支的历史会被覆盖（保持只存最新版本）

6.5 提交并推送

git add .github/
git commit -m "ci: add GitHub Actions deploy workflow"
git push origin main

推送后，打开源码仓库的 Actions 标签页，可以看到工作流正在执行。等待黄色的运行中图标变为绿色勾号，说明部署成功。

七、配置 GitHub Pages

7.1 启用 Pages 服务

1. 打开 Pages 仓库 → Settings → Pages
2. Source 选择 Deploy from a branch
3. Branch 选择 gh-pages，目录选 / (root)
4. 点击 Save

配置完成后，博客即可通过 https://你的用户名.github.io/你的Pages仓库名/ 访问。

7.2 配置自定义域名

绑定自己的域名可以让博客更专业。以下以 blog.example.com 为例：

第一步：在域名 DNS 管理后台添加解析记录

第二步：在 Pages 仓库设置域名

在 Pages 仓库的 Settings → Pages → Custom domain 中输入 blog.example.com，点击 Save。GitHub 会自动签发 SSL/TLS 证书。

第三步：在源码仓库添加 CNAME 文件

在 source/ 目录下创建 CNAME 文件（无扩展名），内容为你的域名：

blog.example.com

[!info] 为什么 CNAME 文件要放在 source/ 目录？
因为 hexo generate 时，source/ 下的所有文件（不含 _posts/ 中的文章）会原样复制到 public/，确保每次构建后 CNAME 文件都在部署目录中。

八、日常写作工作流

所有配置完成后，日常使用就变得非常简单：

# 1. 创建新文章
hexo new post "新文章标题"

# 2. 用任何编辑器编辑 Markdown 文件
#    文件位置：source/_posts/新文章标题.md
code source/_posts/新文章标题.md

# 3. 本地预览（可选，但推荐）
hexo clean && hexo generate && hexo server
# 浏览器访问 http://localhost:4000

# 4. 提交并推送
git add source/_posts/
git commit -m "post: add 新文章标题"
git push

推送后等待 1-2 分钟，GitHub Actions 构建部署完成，博客即自动更新。

九、最佳实践与注意事项

9.1 .gitignore 配置

node_modules/
public/
.deploy_git/
db.json
*.log
.DS_Store

确保 node_modules/ 和 public/ 不提交到 Git 仓库。

9.2 借助 CDN 加速静态资源

国内访问 GitHub Pages 速度较慢，可以使用 jsDelivr CDN 对主题的静态资源进行加速。

以本博客的配置为例，在 _config.yml 中添加 CDN 配置：

cdn:
  enable: true
  url: 'https://cdn.jsdelivr.net/gh/你的用户名/你的源码仓库@main/source'
  vendors:
    highlight_js: 'https://cdn.jsdelivr.net/npm/highlight.js@11.10.0'
    highlight_css: 'https://cdn.jsdelivr.net/npm/highlight.js@11.10.0/styles/atom-one-dark.min.css'

jsDelivr 的 GitHub 加速格式：https://cdn.jsdelivr.net/gh/{用户名}/{仓库}@{分支}/{文件路径}，完全免费，无需注册。

9.3 为文章添加封面图

在文章 YAML 头部添加 cover 字段可以设置封面图，在首页和文章列表中以卡片形式展示。推荐使用图床存储图片，避免图片文件占用源码仓库空间。

---
title: 文章标题
cover: https://图床域名/path/to/cover.jpg
---

9.4 插件推荐

9.5 常见问题排查

Q1：GitHub Actions 构建失败

[!faq]- 查看常见原因

• HEXO_DEPLOY Secret 未配置或 Token 已过期 → 检查 Secrets 设置
• PUBLISH_REPOSITORY 格式错误 → 必须为 用户名/仓库名
• Token 缺少 repo 权限 → 重新生成 Token 时确认勾选 repo

Q2：博客更新但页面未变化

[!faq]- 排查步骤

1. GitHub Pages 部署通常有 1-2 分钟延迟
2. 尝试强制刷新浏览器（Cmd+Shift+R / Ctrl+F5）
3. 确认 GitHub Actions 工作流运行成功（绿色勾号）

Q3：自定义域名 SSL 证书未生效

[!faq]- 原因与解决

• GitHub Pages 的 SSL 证书通过 Let's Encrypt 自动签发，首次配置可能需要等待 5-15 分钟
• 确认 DNS 的 CNAME 记录已正确指向 你的用户名.github.io
• 可以在 Pages 设置页面取消绑定再重新绑定，触发证书重新签发

Q4：图片加载失败

[!faq]- 排查方案

• 确认图片 URL 可公开访问
• 使用图床（如 SM.MS、Cloudflare R2、阿里云 OSS）存储图片
• 或使用 jsDelivr 加速 GitHub 仓库中的图片：https://cdn.jsdelivr.net/gh/用户名/仓库@分支/图片路径

参考资料

• Hexo 官方文档
• GitHub Pages 官方文档
• GitHub Actions 官方文档
• hexo-deploy-github-pages-action
• hexo-abbrlink 插件
• Keep 主题文档
• Butterfly 主题文档
• jsDelivr CDN 文档
• 本博客 GitHub Actions 工作流源码