超详细！Github Actions 自动化部署 Hexo 博客（小白友好版）

之前我们已经完成了 Hexo 博客的本地搭建和手动部署，虽然能正常使用，但每次写文章都要在本地操作、编译、部署，步骤繁琐还受设备限制。而 Github Actions 能帮我们实现”一次配置，终身受益”——把本地编译部署的工作全交给云端自动完成，以后不管用什么设备，只要能编辑文章并推送到 Github，就能自动更新博客。下面就带小白们一步步实现自动化部署，全程图文级详细，跟着做就能成！

一、核心原理先搞懂（不用深究，知道大概就行）

简单说，我们需要准备两个 Github 仓库：

1. 「自动化仓库」（建议私有）：存放 Hexo 博客的原始文件（比如文章草稿、主题配置、源码等），以后写文章就往这个仓库推内容；
2. 「Pages 仓库」（必须公有）：就是之前手动部署时创建的 用户名.github.io 仓库，用来存放 Github Actions 自动编译生成的静态网页文件（访客最终看到的内容）。

Github Actions 的作用是：当「自动化仓库」的代码有变动（比如新增文章、修改配置）时，它会自动触发一个”工作流”——在云端安装 Node.js 环境、Hexo 及相关依赖，编译原始文件生成静态网页，最后把静态网页推送到「Pages 仓库」，完成博客自动更新。

好处就是：以后不用在本地装 Hexo、Node.js，哪怕在网吧、手机（配合 Github 移动端），只要能编辑文章并推送到「自动化仓库」，博客就会自动更新，太方便了！

二、前期准备（必看！少一步都不行）

1. 已经完成 Hexo 博客本地搭建和手动部署到 Github Pages（也就是已经有了 用户名.github.io 这个 Pages 仓库）；
2. 本地电脑已经安装 Git、Node.js（之前搭建 Hexo 时已经装过，不用重新装）；
3. Github 账号已配置好 SSH 密钥（之前手动部署时已经配置过，能正常用 git push 命令就行）。

三、具体操作步骤（一步都别跳！）

第一步：创建「自动化仓库」（存放 Hexo 原始文件）

1. 登录 Github，点击右上角「+」号，选择「New repository」（新建仓库）；
2. 仓库配置如下（重点看说明）：
   • Repository name（仓库名）：随便填，比如 myhexo-source（好记就行，不用和用户名相关）；
   • Description（描述）：可选，比如”Hexo 博客自动化部署源码仓库”；
   • Visibility（可见性）：选「Private」（私有），避免源码被别人看到；
   • 其他选项：不用勾选「Add a README file」「Add .gitignore」「Choose a license」，直接点「Create repository」。

创建成功后，仓库地址会是 https://github.com/你的用户名/myhexo-source.git（记下来，后面要用）。

第二步：整理本地 Hexo 原始文件，上传到「自动化仓库」

这一步是把本地 Hexo 博客的核心文件复制出来，上传到刚创建的「自动化仓库」，重点是”只传有用的文件，多余的别传”。

1. 打开本地电脑的 Hexo 博客根目录（比如之前创建的 blog/hexoblog 文件夹），里面有这些文件/文件夹，我们只需要复制以下 7 个（其他的不用管）：

   • .github（如果没有这个文件夹，后续创建 workflow 时会自动生成，先不用管）；
   • scaffolds（文章模板文件夹）；
   • source（文章存放文件夹，你的博客文章都在这里）；
   • themes（主题文件夹，比如你用的 bamboo 主题）；
   • _config.yml（博客核心配置文件）；
   • package.json（依赖配置文件）；
   • package-lock.json（依赖版本锁定文件）。

2. 关键操作：删除主题文件夹里的 .git 目录！
   进入 themes/你的主题名（比如 themes/bamboo），找到一个叫 .git 的隐藏文件夹（Windows 要先开启”显示隐藏文件”），必须删除！不然上传时会冲突，导致部署失败（这是很多小白踩坑的点）。

3. 在本地新建一个文件夹（比如 myhexo-upload），把上面复制的 7 个文件/文件夹粘贴到这个新文件夹里；

4. 上传这些文件到「自动化仓库」：

   • 右键点击新文件夹 myhexo-upload，选择「Git Bash Here」（Windows）或打开终端（Linux/Mac）；
   • 依次输入以下命令（每输完一条按回车，注意替换括号里的内容）：

     1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17

     # 1. 初始化本地仓库（把这个文件夹变成 Git 可管理的仓库） git init # 2. 添加所有文件到缓存区（后面的点不能漏，表示"当前目录所有文件"） git add . # 3. 提交缓存区文件到本地仓库，备注信息可以随便改，比如"初始化 Hexo 源码" git commit -m "first commit: 上传 Hexo 原始文件" # 4. 关联 Github 上的「自动化仓库」（替换成你的仓库地址） # 两种方式选一种：SSH 方式（之前配置过 SSH 密钥的用这个，不用输密码） git remote add origin git@github.com:你的用户名/myhexo-source.git # 或者 HTTPS 方式（没配置 SSH 用这个，后续 push 会提示输 Github 账号密码） git remote add origin https://github.com/你的用户名/myhexo-source.git # 5. 把本地文件推送到 Github 「自动化仓库」的 master 分支（现在 Github 默认分支是 main，也可以用 main，后续保持一致即可） git push -u origin master

   • 推送成功后，打开 Github 上的「自动化仓库」，能看到刚才上传的 7 个文件/文件夹，就说明这一步搞定了！

第三步：获取 Github Token（给 Actions 授权，让它能操作你的仓库）

Github Actions 需要一个 Token 来获取你的仓库操作权限，按以下步骤生成：

1. 登录 Github，点击右上角头像 →「Settings」（设置）→ 拉到最下面点击「Developer settings」（开发者设置）→「Personal access tokens」（个人访问令牌）→「Tokens (classic)」→「Generate new token (classic)」（生成新的经典令牌）；
2. 配置 Token：
   • Note（备注）：随便填，比如”Hexo 自动化部署 Token”；
   • Expiration（有效期）：选「No expiration」（永不过期，省得以后重新生成）；
   • Select scopes（权限勾选）：只需要勾选「repo」（所有 repo 相关权限）和「workflow」（工作流权限），其他的都不用勾；
3. 点击最下面「Generate token」（生成令牌），生成后会出现一串随机字符串（比如 ghp_vNdFxxxxxxxxxxxxxxxxxxxx），这串字符只显示一次！一定要复制下来保存好（比如存到记事本里），后面要用，丢了就只能重新生成。

第四步：在「自动化仓库」添加 Secret（隐藏 Token，避免泄露）

我们不能把 Token 直接写在配置文件里，需要用 Github 的 Secret 功能隐藏起来：

1. 打开「自动化仓库」（比如 myhexo-source），点击「Settings」（设置）→ 左侧「Secrets and variables」（密钥和变量）→「Actions」→「New repository secret」（新建仓库密钥）；
2. 按以下表格添加 3 个 Secret（添加完一个点「Add secret」，再添加下一个）：

添加完成后，在「Repository secrets」列表里能看到这 3 个变量名（值是隐藏的，看不到），就对了。

第五步：创建 Github Actions 工作流（核心！告诉 Actions 该怎么做）

工作流是一个 YAML 配置文件，用来告诉 Github Actions 触发条件、执行步骤（比如安装环境、编译文件、部署到 Pages 仓库）：

1. 打开「自动化仓库」→ 点击顶部「Actions」→ 点击「set up a workflow yourself」（自己设置工作流）；
2. 进入编辑页面，把默认的代码全删掉，复制下面的代码粘贴进去（直接复制即用）：

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
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86

name: 自动部署

on:
  push:
    branches:
      - main
  release:
    types:
      - published

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: 检查代码
        uses: actions/checkout@v4
        with:
          ref: main
          fetch-depth: 0

      - name: 安装 Node.js（降级到稳定组合）
        uses: actions/setup-node@v4
        with:
          node-version: "18.x"  # 18.x + Hexo 7.x 完美稳定无兼容问题
          cache: "npm"

      - name: 安装依赖（使用稳定版 Hexo，保留你的优化逻辑）
        run: |
          export TZ='Asia/Shanghai'
          # 卸载可能存在的高版本hexo，安装稳定的4.0.0版本
          npm uninstall -g hexo-cli
          npm install -g hexo-cli@4.0.0
          # 初始化package.json（如果不存在）
          if [ ! -f "package.json" ]; then
            npm init -y
          fi
          # 安装Hexo 7.x（彻底避免8.x的ES Module兼容性问题）
          npm install hexo@7.3.0 --save
          # 安装必要的部署依赖，必装！
          npm install hexo-deployer-git --save
          # 调试信息：查看已安装的包版本，方便排错
          npm list hexo
          hexo version

      - name: 生成静态文件（增加错误检查，保留你的优化逻辑）
        run: |
          # 清理并生成，输出详细日志，方便排查生成失败问题
          hexo clean
          hexo generate --verbose
          # 检查public目录是否生成，无则直接终止并报错
          if [ -d "./public" ]; then
            echo "✅ public目录生成成功，目录内容如下："
            ls -la ./public
          else
            echo "❌ public目录生成失败，终止部署！"
            cat _config.yml || echo "无_config.yml核心配置文件"
            exit 1
          fi

      - name: 部署到GitHub Pages（核心优化+修复，100%推送到main分支）
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUBTOKEN }}
          GITHUB_USERNAME: ${{ secrets.GITHUBUSERNAME }}
          GITHUB_EMAIL: ${{ secrets.GITHUBEMAIL }}
        run: |
          # 双重确认public目录存在，防止生成步骤检测失效
          if [ ! -d "./public" ]; then
            echo "错误：public目录不存在，部署终止"
            exit 1
          fi
        
          cd ./public
          git init
          git config --global user.name "$GITHUB_USERNAME"
          git config --global user.email "$GITHUB_EMAIL"
          git add -A
        
          # 处理空提交，无文件变更则跳过，避免部署失败
          if git diff --quiet --staged; then
            echo "ℹ️ 无文件变更，跳过本次提交和推送"
            exit 0
          fi
        
          git commit -m "Auto deploy: ${{ github.event.head_commit.message }} | $(date +'%Y-%m-%d %H:%M:%S %Z')"
          # 核心加固：明确指定推送到你的pages仓库【main分支】，语法绝对正确
          git push --force "https://$GITHUB_USERNAME:$GITHUB_TOKEN@github.com/$GITHUB_USERNAME/$GITHUB_USERNAME.github.io.git" master:main

3. 粘贴完成后，点击右上角「Commit changes…」（提交更改），在弹出的窗口里直接点「Commit changes」，工作流就创建成功了！

第六步：测试自动化部署是否成功

1. 工作流创建后，会自动执行一次（因为刚才的「Commit changes」也是一次 push 操作）；
2. 点击「自动化仓库」的「Actions」标签，能看到正在运行的工作流（绿色的对勾表示成功，红色的叉表示失败）；
3. 等待 1-3 分钟（取决于网络和依赖安装速度），如果最后显示「Success」，说明部署成功！
4. 验证：打开你的 Pages 仓库（用户名.github.io），能看到 public 文件夹里的静态文件（比如 index.html）已经被更新；打开浏览器访问 https://用户名.github.io，能看到博客正常显示，就大功告成了！

第七步：后续使用（小白最关心的部分）

以后写新文章、修改博客配置，只需要做 3 步：

1. 编辑文章：在本地的 source/_posts 文件夹里新建 Markdown 文章（比如 我的第一篇自动化文章.md），写好内容；
2. 推送代码：进入本地「自动化仓库」的文件夹（myhexo-upload），右键打开 Git Bash，输入以下命令：

   1 2 3

   git add . # 添加新文章/修改的文件 git commit -m "新增文章：我的第一篇自动化文章" # 备注信息 git push origin master # 推送到 Github 「自动化仓库」

3. 等待自动部署：推送成功后，Github Actions 会自动触发工作流，1-3 分钟后访问博客，就能看到新文章了！

四、常见问题排查（小白避坑指南）

1. 工作流执行失败，提示「找不到分支」：

   • 检查工作流配置文件里的 branches: - master 是否和你的「自动化仓库」分支一致（如果你的分支是 main，就把 master 改成 main）；
   • 检查 Pages 仓库的分支是否是 master（现在 Github 默认分支是 main，需要在 Pages 仓库的「Settings」→「Pages」→「Branch」里改成 master）。

2. 提示「权限不足」：

   • 检查第三步的 Token 是否勾选了「repo」和「workflow」权限；
   • 检查第四步的 Secret 变量名是否正确（GITHUBUSERNAME、GITHUBEMAIL、GITHUBTOKEN 不能写错）；
   • 重新生成 Token 并更新 Secret，再试一次。

3. 部署成功但博客没更新：

   • 清除浏览器缓存（按 Ctrl+Shift+R 强制刷新）；
   • 检查 Pages 仓库是否真的被更新（看最新的提交记录）；
   • 等待 5-10 分钟（Github Pages 可能有缓存延迟）。

4. 主题显示异常：

   • 确认已经删除了 themes/主题名/.git 文件夹；
   • 检查 _config.yml 里的主题配置是否正确（theme: 你的主题名）。

按照上面的步骤操作，小白也能轻松实现 Hexo 博客的自动化部署，以后再也不用手动执行 hexo clean && hexo g && hexo d 了，随时随地都能更新博客，赶紧试试吧！如果遇到问题，欢迎在评论区留言~