github action 自动部署 hexo
写博客之后,每篇文章都要分别更新两个仓库:源码仓库 your-username/blog 和 GitHub Pages 仓库 your-username/your-username.github.io。手动敲 hexo g -d 容易忘记,而 GitHub Actions 可以把它变成"push 源码,自动构建发布":
1 | |
下面按当前仓库的实际方案(SSH 部署密钥 + hexo-deployer-git)写,文末再给一个完全不需要密钥的替代方案。
一、配置 Hexo 部署目标
_config.yml 里的 deploy 段指定 Pages 仓库和分支:
1 | |
hexo-deployer-git 会读取这里配置,负责把 public/ 目录的内容推到目标仓库。
二、生成专用部署密钥
不要复用你日常使用的 SSH 密钥:一旦某个 GitHub 账号或仓库配置泄露,专用密钥只影响这一个 Pages 仓库,损失最小。
1 | |
连续回车(不设 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,值粘贴整个私钥文件内容:
Settings → Actions中新建 workflow:
.github/workflows/main.yml:
1 | |
上面的示例与仓库根目录
.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,与本地密钥文件名无关。

随后 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 | |
然后在 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,喝口水,站点自己就更新了。
