Hexo 博客 GitHub Actions 自动部署备忘录

1. 部署目的

用自动化流程替代手动编译。本地不再需要维护 Node.js 和 Docker 环境，只需编写 Markdown 源码并 push 代码。环境搭建、网页生成和发布操作交由 GitHub Actions 自动完成。

2. 分支策略

仓库使用双分支管理：

Source 分支：作为默认分支，存放 Markdown 源码、Hexo 配置文件、主题文件及 package.json。
Hexo 分支：作为展示分支，只存放云端编译后生成的静态 HTML 网页，供 GitHub Pages 读取。

3. 初始配置步骤

获取 Token

登录 GitHub，进入 Settings -> Developer settings -> Personal access tokens (classic)。
点击生成新 Token，期限选 No expiration，权限勾选 repo 和 workflow。
复制生成的 ghp_... 字符串保存备用。

配置仓库 Secret

进入博客的 GitHub 仓库页面，点击 Settings -> Secrets and variables -> Actions。
新建 Repository secret，Name 填 GH_TOKEN，Secret 填入刚才复制的 Token。

配置本地 .gitignore
确保本地 Hexo 根目录存在 .gitignore 文件，过滤掉无需上传的生成文件和依赖项。包含以下内容：

.DS_Store
Thumbs.db
db.json
*.log
node_modules/
public/
.deploy*/

编写 Actions 工作流脚本
在本地 Hexo 根目录创建文件：.github/workflows/deploy.yml。填入以下代码：

name: Deploy Hexo Blog

on:
  push:
    branches:
      - Source

jobs:
  build:
    runs-on: ubuntu-latest
    
    steps:
      - name: Checkout Source
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Cache node modules
        uses: actions/cache@v4
        env:
          cache-name: cache-node-modules
        with:
          path: node_modules
          key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ hashFiles('**/package-lock.json') }}
          restore-keys: |
            ${{ runner.os }}-build-${{ env.cache-name }}-

      - name: Install Dependencies
        run: |
          npm install -g hexo-cli
          npm install

      - name: Build Hexo
        run: |
          hexo clean
          hexo generate

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          personal_token: ${{ secrets.GH_TOKEN }}
          publish_dir: ./public   
          publish_branch: Hexo

注：此方案直接使用 actions-gh-pages 插件推送，无需再配置 _config.yml 中的 deploy 字段。

设置 GitHub Pages 源
进入仓库 Settings -> Pages，在 Build and deployment 选项中，Source 选择 Deploy from a branch，Branch 选择 Hexo 分支和 / (root) 目录，保存。

配置本地 Git 免密
在本地终端执行以下命令记录凭据，后续 push 代码无需重复输入 Token：

1	git config --global credential.helper store

4. 日常发布流程

配置完成后，日常写完文章或修改配置，只需在根目录执行 Git 提交命令：

1
2
3

git add .
git commit -m "更新文章"
git push origin Source

代码推送到 Source 分支后，GitHub Actions 会自动触发并在后台完成编译和网页发布。

5. 常见问题记录

弃用 hexo-deployer-git 的原因
Hexo 原生的部署插件在 CI/CD 环境下容易因变量解析失败或 SSH 权限缺失报错。改用第三方的部署 Action 可以绕过这些不稳定因素。
推送时出现 [rejected] 报错
说明云端仓库的内容与本地不一致产生冲突。在确认本地源码是最新的前提下，可使用 -f 参数强制推送覆盖云端：git push -f origin Source。
仓库中多出 dependabot 相关分支
这是 GitHub 自动检查依赖更新的机器人。当检测到 Hexo 程序或主题有新版本时，会自动创建分支并提交 Pull request。可以在网页端确认合并以升级版本，或者不予理会。

使用Github Actions自动化推送Hexo博客