本教程基于：Hexo 7.x + Fluid 主题（npm 安装方式）+ GitHub Actions + 跨仓库部署到 GitHub Pages
一、整体架构说明
本方案使用两个 GitHub 仓库分离源码与静态文件：
1
2
3
4
5
6
7
| my-blog-source（私有/公开） iomelons.github.io（公开）
├── source/_posts/ → ├── index.html
├── themes/ → ├── archives/
├── _config.yml → ├── css/
└── package.json → └── js/
源码仓库 Pages 仓库
（你写文章、改配置） （存放编译后的静态文件）
|
工作流程：
- 你在本地写文章，
git push 到 my-blog-source 的 main 分支
- GitHub Actions 自动触发，安装依赖、运行
hexo generate
- 将
public/ 目录的静态文件推送到 iomelons.github.io 的 main 分支
- GitHub Pages 自动发布，博客更新完成
二、前置准备
2.1 安装本地环境
1
2
3
4
5
6
7
8
|
npm install -g hexo-cli
hexo version
|
2.2 初始化 Hexo 项目
1
2
3
4
5
6
7
8
9
10
11
|
hexo init my-blog-source
cd my-blog-source
npm install
npm install hexo-theme-fluid
hexo server
|
2.3 创建 GitHub 仓库
在 GitHub 上创建两个仓库：
| 仓库名 |
说明 |
建议可见性 |
my-blog-source |
存放 Hexo 源码 |
私有或公开均可 |
your-username.github.io |
存放编译后的静态文件 |
必须公开 |
your-username.github.io 命名格式固定，将作为 GitHub Pages 的默认域名。
三、配置文件详解
3.1 Hexo 根配置 _config.yml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
|
title: 我的博客
subtitle: ''
description: '个人技术博客'
keywords:
author: 你的名字
language: zh-CN
timezone: 'Asia/Shanghai'
url: https://your-username.github.io
root: /
source_dir: source
public_dir: public
theme: fluid
|
3.2 Fluid 主题配置 _config.fluid.yml
在项目根目录新建 _config.fluid.yml，**不要直接修改 themes/fluid/_config.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
|
navbar:
blog_title: "你的博客名"
menu:
- { key: "home", link: "/", icon: "iconfont icon-home-fill" }
- { key: "archive", link: "/archives/", icon: "iconfont icon-archive-fill" }
- { key: "about", link: "/about/", icon: "iconfont icon-user-fill" }
index:
banner_img: https://fastly.jsdelivr.net/gh/fluid-dev/static@master/hexo-theme-fluid/wallpaper.jpg
banner_img_height: 80
slogan:
enable: true
text: "你的个性签名"
post:
banner_img_height: 60
math:
enable: false
mermaid:
enable: false
footer:
content: '由 <a href="https://hexo.io" target="_blank">Hexo</a> 驱动，主题使用 <a href="https://github.com/fluid-dev/hexo-theme-fluid" target="_blank">Fluid</a>'
|
完整配置项参考 Fluid 官方文档：https://hexo.fluid-dev.com/docs/guide/
3.3 确认 package.json
根目录的 package.json 应包含所有必要依赖：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
| {
"name": "my-blog-source",
"version": "1.0.0",
"private": true,
"scripts": {
"build": "hexo generate",
"clean": "hexo clean",
"server": "hexo server"
},
"dependencies": {
"hexo": "^7.0.0",
"hexo-generator-archive": "^2.0.0",
"hexo-generator-category": "^2.0.0",
"hexo-generator-index": "^3.0.0",
"hexo-generator-tag": "^2.0.0",
"hexo-renderer-ejs": "^2.0.0",
"hexo-renderer-marked": "^6.0.0",
"hexo-renderer-stylus": "^3.0.0",
"hexo-server": "^3.0.0",
"hexo-theme-fluid": "^1.9.8"
}
}
|
依赖安装完后，务必生成 lock 文件并提交：
1
2
3
| npm install
git add package.json package-lock.json
git commit -m "chore: add package-lock.json"
|
四、配置 GitHub Personal Access Token
GitHub Actions 需要有权限向另一个仓库（your-username.github.io）推送代码，需要配置 Personal Access Token（PAT）。
4.1 生成 Token
- 登录 GitHub → 右上角头像 → Settings
- 左侧菜单最底部 → Developer settings
- Personal access tokens → Tokens (classic) → Generate new token
- 填写说明，例如
hexo-deploy
- 勾选权限：
repo（完整勾选，包含子选项）
- 点击 Generate token，复制生成的 Token（只显示一次，务必保存）
4.2 添加到仓库 Secrets
- 打开
my-blog-source 仓库
- Settings → Secrets and variables → Actions
- 点击 New repository secret
- Name 填写：
GH_TOKEN
- Value 粘贴刚才复制的 Token
- 点击 Add secret
五、GitHub Actions Workflow 配置
在项目根目录创建 .github/workflows/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
| name: Hexo Deploy
on:
push:
branches:
- main
jobs:
build-and-deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout 源码
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: 安装 Node.js
uses: actions/setup-node@v4
with:
node-version: '18'
cache: 'npm'
- name: 安装 Hexo CLI
run: npm install -g hexo-cli
- name: 安装依赖
run: npm ci
- name: 清理缓存
run: hexo clean
- name: 生成静态文件
run: hexo generate --verbose
- name: 验证生成结果
run: |
HTML_COUNT=$(find ./public -name "*.html" | wc -l)
INDEX_SIZE=$(wc -c < ./public/index.html)
echo "HTML 文件数量: $HTML_COUNT"
echo "index.html 大小: $INDEX_SIZE bytes"
if [ "$INDEX_SIZE" -lt 100 ]; then
echo "❌ index.html 疑似空文件，终止部署"
exit 1
fi
echo "✅ 构建验证通过"
- name: 部署到 GitHub Pages
uses: peaceiris/actions-gh-pages@v3
with:
personal_token: ${{ secrets.GH_TOKEN }}
external_repository: your-username/your-username.github.io
publish_branch: main
publish_dir: ./public
commit_message: "ci: deploy from ${{ github.sha }}"
user_name: 'github-actions[bot]'
user_email: 'github-actions[bot]@users.noreply.github.com'
|
注意将 external_repository 替换为你自己的用户名。
六、配置 GitHub Pages
6.1 在 Pages 仓库启用 GitHub Pages
- 打开
your-username.github.io 仓库
- Settings → Pages
- Source 选择 Deploy from a branch
- Branch 选择
main，目录选择 / (root)
- 点击 Save
几分钟后访问 https://your-username.github.io 即可看到博客。
七、完整项目目录结构
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
| my-blog-source/
├── .github/
│ └── workflows/
│ └── deploy.yml ← GitHub Actions 配置
├── source/
│ ├── _posts/
│ │ └── hello-world.md ← 你的文章
│ └── about/
│ └── index.md
├── scaffolds/
├── themes/ ← 为空或不存在（主题通过 npm 安装）
├── _config.yml ← Hexo 全局配置
├── _config.fluid.yml ← Fluid 主题配置
├── package.json ← 依赖声明（含 hexo-theme-fluid）
└── package-lock.json ← 依赖锁定文件（必须提交）
|
八、日常写作流程
配置完成后，日常只需以下步骤：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
|
hexo new "我的新文章"
hexo server
git add .
git commit -m "post: 我的新文章"
git push
|
九、常见问题排查
Q1：Actions 报错 Dependencies lock file is not found
原因：package-lock.json 未提交到仓库，或被 .gitignore 排除。
解决：
1
2
3
4
5
6
7
|
grep "package-lock" .gitignore
git add -f package-lock.json
git commit -m "fix: track package-lock.json"
git push
|
Q2：生成的 HTML 文件全是空文件
原因：Hexo 找不到主题模板（layout），通常是主题安装不完整。
解决：确认 package.json 中有 hexo-theme-fluid，并且 package-lock.json 已提交，让 CI 通过 npm ci 完整安装主题。
Q3：Actions 报错 Resource not accessible by integration
原因：GH_TOKEN 权限不足，或 Secret 名称填写有误。
解决：检查 Token 是否勾选了 repo 权限，Secret 名称是否与 workflow 中的 secrets.GH_TOKEN 一致。
Q4：推送后 Pages 没有更新
原因：your-username.github.io 仓库的 Pages 设置未正确配置。
解决：确认 Settings → Pages → Source 设置为 main 分支根目录，并等待 GitHub Pages 重新构建（通常需要 1~3 分钟）。
Q5：本地 hexo server 正常但 CI 构建失败
原因：本地 node_modules 状态与 package-lock.json 不一致，导致 CI 安装的依赖版本有差异。
解决：
1
2
3
4
5
6
|
rm package-lock.json
npm install
git add package-lock.json
git commit -m "fix: regenerate package-lock.json"
git push
|
十、进阶优化
10.1 缓存加速
在 workflow 中 setup-node 加上 cache: 'npm' 后，GitHub Actions 会自动缓存 node_modules，后续构建速度可提升 50% 以上。
10.2 仅在文章变更时触发构建
1
2
3
4
5
6
7
8
9
| on:
push:
branches:
- main
paths:
- 'source/**'
- '_config.yml'
- '_config.fluid.yml'
- 'package.json'
|
这样只有修改了文章或配置时才触发，避免修改 README 等文件时浪费 CI 时间。
10.3 绑定自定义域名
在 source/ 目录下创建 CNAME 文件：
peaceiris/actions-gh-pages 会自动将该文件复制到部署目录，防止每次部署后自定义域名被重置。
十一、完整 workflow 最终版本
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
| name: Hexo Deploy
on:
push:
branches:
- main
paths:
- 'source/**'
- '_config.yml'
- '_config.fluid.yml'
- 'package.json'
- 'package-lock.json'
jobs:
build-and-deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout 源码
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: 安装 Node.js
uses: actions/setup-node@v4
with:
node-version: '18'
cache: 'npm'
- name: 安装 Hexo CLI
run: npm install -g hexo-cli
- name: 安装依赖
run: npm ci
- name: 清理缓存
run: hexo clean
- name: 生成静态文件
run: hexo generate --verbose
- name: 验证生成结果
run: |
HTML_COUNT=$(find ./public -name "*.html" | wc -l)
INDEX_SIZE=$(wc -c < ./public/index.html)
echo "HTML 文件数量: $HTML_COUNT"
echo "index.html 大小: $INDEX_SIZE bytes"
if [ "$INDEX_SIZE" -lt 100 ]; then
echo "❌ index.html 疑似空文件，终止部署"
exit 1
fi
echo "✅ 构建验证通过"
- name: 部署到 GitHub Pages
uses: peaceiris/actions-gh-pages@v3
with:
personal_token: ${{ secrets.GH_TOKEN }}
external_repository: your-username/your-username.github.io
publish_branch: main
publish_dir: ./public
commit_message: "ci: deploy from ${{ github.sha }}"
user_name: 'github-actions[bot]'
user_email: 'github-actions[bot]@users.noreply.github.com'
|