github action 自动部署 hexo

写博客之后,每篇文章都要分别更新两个仓库:源码仓库 your-username/blog 和 GitHub Pages 仓库 your-username/your-username.github.io。手动敲 hexo g -d 容易忘记,而 GitHub Actions 可以把它变成"push 源码,自动构建发布":

1
2
3
4
5
6
7
your-username/blog (master)  push
│
▼
GitHub Actions:checkout → Node.js → npm ci → hexo generate
│ SSH deploy key / 或 GitHub Pages Actions
▼
your-username/your-username.github.io (master) → your-username.github.io

下面按当前仓库的实际方案(SSH 部署密钥 + hexo-deployer-git)写,文末再给一个完全不需要密钥的替代方案。

一、配置 Hexo 部署目标

_config.yml 里的 deploy 段指定 Pages 仓库和分支:

1
2
3
4
deploy:
type: git
repo: git@github.com:your-username/your-username.github.io.git
branch: master

hexo-deployer-git 会读取这里配置,负责把 public/ 目录的内容推到目标仓库。

二、生成专用部署密钥

不要复用你日常使用的 SSH 密钥:一旦某个 GitHub 账号或仓库配置泄露,专用密钥只影响这一个 Pages 仓库,损失最小。

1
ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519_hexo -C "hexo-action-deploy"

连续回车(不设 passphrase;密钥内容整体交给 GitHub 密钥管理,CI 里才能直接使用):

  • 私钥 ~/.ssh/id_ed25519_hexo → 填进 blog 源码仓库 的 Actions Secret;
  • 公钥 ~/.ssh/id_ed25519_hexo.pub → 加到 Pages 仓库 的 Deploy keys,并勾选 Allow write access。

老教程常用 ssh-keygen -t rsa;新配置优先用 ed25519,更短更安全。仓库当前沿用 RSA 密钥也没问题:下文 CI 把私钥统一写为 ~/.ssh/deploy_key,再通过 git config --global core.sshCommand 显式指定,不依赖 id_rsa / id_ed25519 这类默认文件名;ssh-keyscan 同时收录 RSA 与 Ed25519 主机公钥。

三、配置 blog 源码仓库

  • Settings → Secrets and variables → Actions → New repository secret,名称 HEXO_DEPLOY_PRIVATE_KEY,值粘贴整个私钥文件内容:

    添加 Actions Secret

  • Settings → Actions 中新建 workflow:

    新建 GitHub Actions 工作流

.github/workflows/main.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
name: Hexo Blog CI

on:
push:
branches: [master]

permissions:
contents: read

jobs:
deploy:
runs-on: ubuntu-latest

steps:
- name: Checkout
uses: actions/checkout@v4

- name: Setup Node.js 22.16.0
uses: actions/setup-node@v4
with:
node-version: "22.16.0"
cache: npm # 需要有 package-lock.json

- name: Install dependencies
run: |
npm ci
npm install -g hexo-cli

- name: Setup Deploy Private Key
env:
HEXO_DEPLOY_PRIVATE_KEY: ${{ secrets.HEXO_DEPLOY_PRIVATE_KEY }}
run: |
mkdir -p ~/.ssh
echo "$HEXO_DEPLOY_PRIVATE_KEY" > ~/.ssh/deploy_key
chmod 600 ~/.ssh/deploy_key
ssh-keyscan -t rsa,ed25519 github.com >> ~/.ssh/known_hosts
# 让后续 git push 只使用这把部署密钥,不依赖默认文件名
git config --global core.sshCommand "ssh -i $HOME/.ssh/deploy_key -o IdentitiesOnly=yes"

- name: Setup Git Information
run: |
git config --global user.name "github-actions[bot]"
git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com"

- name: Deploy
run: |
hexo clean
hexo generate
hexo deploy

上面的示例与仓库根目录 .github/workflows/main.yml 保持一致。

几个关键点:

  • 版本别钉死方式过时的写法:actions/checkout@master、actions/setup-node@master 这类跟随默认分支的引用不稳定,何时变更行为你毫不知情;改用主版本 tag(@v4),更严格可钉完整 commit SHA;
  • Node 版本:Hexo 8 要求 node >= 20.19,Node 18.x 及以下会直接报错;仓库当前钉在 22.16.0,想跟随 LTS 主线可写 22;
  • 缓存:cache: npm 依赖 package-lock.json;没有锁文件就换回 npm install + actions/cache;
  • 生成顺序:hexo clean 会删掉 public,hexo deploy 发现 public 不存在时会自动补一次 generate(Hexo 源码逻辑),但显式写出 hexo generate 更容易理解,也避免依赖这个隐式行为;
  • git 身份:hexo-deployer-git 向 Pages 仓库提交时用的是全局 user.name/user.email,必须配置;这里使用 github-actions[bot] 的 noreply 身份,避免在提交记录中暴露个人邮箱;
  • 部署密钥文件名解耦:core.sshCommand 让 git push 显式使用 ~/.ssh/deploy_key,并用 IdentitiesOnly=yes 避免 Runner 上其他 SSH 身份干扰;RSA 或 Ed25519 私钥都能用,只需与 Pages 仓库 Deploy key 的公钥配对。

四、配置 Pages 仓库

进入 your-username/your-username.github.io 仓库:Settings → Deploy keys → Add deploy key,粘贴 ~/.ssh/id_ed25519_hexo.pub 的内容,务必勾选 Allow write access,否则部署时会被拒绝。若当前仓库沿用 RSA 密钥,则粘贴该私钥对应的 .pub 文件即可;workflow 已通过 core.sshCommand 指定 ~/.ssh/deploy_key,与本地密钥文件名无关。

添加 Deploy key

随后 Actions 里就只有这一台机器(GitHub Runner)持有私钥,能向该仓库写入。

五、常见问题

现象排查方向
Permission denied (publickey)公钥没加进 Pages 仓库的 Deploy keys,或 Secret 里贴成了公钥/缺行;确认 chmod 600,且 workflow 的 core.sshCommand 指向 ~/.ssh/deploy_key
Host key verification failed检查 ssh-keyscan -t rsa,ed25519 github.com 是否执行、known_hosts 是否写入
Actions 全绿但页面没更新看 Pages 仓库是否有新提交;可能是浏览器/Pages 缓存,等几分钟再强刷
npm ci 报错 lock 文件不一致改用 npm install,或重新生成 package-lock.json
提示 Hexo 要求 Node 版本把 node-version 升到 20.19+;不要锁 18 及以下
deploy 时"nothing to commit"确认 Pages 仓库分支是 _config.yml 里配置的 master,且 public/ 确实有变化
密钥可能已泄露立即删除旧 Deploy key,重新生成一对密钥,并轮换 Secret

六、免密钥方案:GitHub Pages × Actions 部署

如果不想管理 SSH 密钥,可以把 Pages 的构建部署完全交给 Actions 制品,特别适合 GitHub Pages 这种"只提供静态文件"的场景:

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
name: Deploy Pages

on:
push:
branches: [master]

permissions:
contents: read
pages: write
id-token: write

jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
cache: npm
- run: npm ci
- run: npm install -g hexo-cli
- run: hexo generate
- uses: actions/upload-pages-artifact@v3
with:
path: public
- uses: actions/deploy-pages@v4

然后在 Pages 仓库(或源仓库,取决于站点类型)的 Settings → Pages → Build and deployment 把 Source 改为 GitHub Actions。GitHub 会把 public/ 作为 Pages 制品直接发布,your-username/your-username.github.io 不再需要接收 push。注意:跨仓库用内置 GITHUB_TOKEN 推另一个仓库是不允许的(它只作用于当前仓库);这也是为什么"源码仓 + 独立 Pages 仓"这种结构下,SSH 部署密钥(或 PAT)更常见。要收敛运维面,就把发布完全迁到 Pages Actions 上。

七、小结

  • 源码仓 + 独立 Pages 仓:专用 SSH 部署密钥,权限最小、配置简单,也兼容 hexo-deployer-git;用 core.sshCommand 指定私钥,RSA / Ed25519 都可用;
  • 不想管理密钥:用 actions/upload-pages-artifact + actions/deploy-pages,在 Pages 设置里切到 GitHub Actions;
  • 无论哪种方案,都从本地 hexo g -d 的重复劳动里解放出来了:写完 git push,喝口水,站点自己就更新了。

参考资料

  1. GitHub Actions 工作流语法
  2. Hexo 部署文档
  3. GitHub Pages 部署 action

github action 自动部署 hexo
https://bubao.github.io/posts/1fbf14ad.html
作者
一念
发布于
2021年3月10日
许可协议