GitHub Actions 自动化部署工作流配置详解

告别繁琐的手动部署，实现“推送即上线”是 Hexo 博客进阶的必经之路。利用 GitHub Actions，你可以让服务器自动接管构建与部署的脏活累活。以下是一套经过实战检验、稳定高效的自动化配置方案。

一、核心优势：为什么选择单仓库+分支管理

目前主流且最高效的做法是使用“单仓库+分支管理”。你只需在一个仓库内同时存放“Hexo 源码”和“生成的网页”，无需跨仓库配置复杂的 Personal Access Token (PAT)。
具体策略为：将 main 分支用来存放 Hexo 源码（包含 _config.yml、source/、themes/ 等），而将 GitHub Pages 的发布源指向自动生成的 gh-pages 分支。这样既能保证源码的安全与整洁，又能实现无缝部署。

二、仓库初始化与源码推送

如果你的仓库目前存放的是生成的 HTML 静态文件，需要将其“清空”并替换为源码。
首先，在本地 Hexo 项目根目录下执行 git init，并关联你的远程仓库。接着，将本地最新的源码强制推送到远程的 main 分支（git push -f origin main）。
️ 关键提醒：强制推送后，你的 GitHub Pages 访问会暂时失效，因为此时 main 分支里全是源码，没有可供展示的 HTML。这是正常现象，接下来的自动化配置将解决这个问题。同时，务必检查 .gitignore 文件，确保 public/ 目录被忽略，我们不需要把本地生成的 HTML 传上去。

三、编写自动化工作流文件

在你的本地 Hexo 根目录下，手动创建 .github/workflows/deploy.yml 文件。这是 GitHub Actions 的核心配置文件，以下是一个稳定且包含缓存优化的标准模板：

name: Hexo Deploy

on:
  push:
    branches:
      - main # 只有推送至 main 分支时才触发

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          submodules: true # 如果你的主题是 git submodule 引入的，必须加这行

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '20' # 建议使用 LTS 版本，与本地保持一致

      - name: Cache dependencies
        uses: actions/cache@v3
        with:
          path: node_modules
          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}

      - name: Install Dependencies
        run: npm install

      - name: Generate
        run: npm run build # 对应 hexo generate

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public
          publish_branch: gh-pages

在这个脚本中，actions/checkout@v4 负责将你的源码下载到 GitHub 分配的虚拟机上；actions/setup-node@v4 负责安装 Node.js 运行环境；而 peaceiris/actions-gh-pages@v3 则是社区极其成熟的部署插件，它会自动将 public 文件夹下的内容推送到 gh-pages 分支。

四、完善配置与触发部署

将工作流文件保存并推送到 GitHub 后，还需要进行最后两项关键设置：

修改 GitHub Pages 设置：进入仓库的 Settings -> Pages，在 Build and deployment 下方的 Branch 选项中，将分支从 main 改为 gh-pages，目录保持 / (root)，然后点击 Save。
禁用 Jekyll 解析：GitHub Pages 默认会使用 Jekyll 引擎解析网页，这会导致 Hexo 生成的包含下划线（如 _static）的文件被忽略。为了防止覆盖，请在 Hexo 源码的根目录下创建一个名为 .nojekyll 的空文件，并将其推送到仓库。