使用 GitHub Actions 在 GitHub Pages 上部署 Hexo 博客

Tech Hexo GitHub Pages GitHub Actions

Word count: 2.6kReading time: 10 min

 2026/03/05 

前言

什么是 GitHub Pages?

GitHub Pages 是 GitHub 提供的免费静态网站托管服务
你只需要将网站文件推送到 GitHub 仓库,就能通过 username.github.io 这样的域名访问你的网站
它支持自定义域名,无需购买服务器,非常适合搭建个人博客、项目文档等静态网站

什么是 Hexo?

Hexo 是一个快速、简洁且高效的博客框架
它基于 Node.js 开发,使用 Markdown 解析文章,能够在几秒内生成静态网页
Hexo 还拥有丰富的主题和插件生态,可以轻松打造个性化的博客

工作原理

本教程采用的方案是:

使用 私有仓库 存储 Hexo 源文件(Markdown 文章、配置文件等)
使用 公开仓库 托管生成的静态网页文件
通过 GitHub Actions 实现自动化构建和部署

当你向私有仓库推送更新时,GitHub Actions 会自动:

安装 Hexo 环境
根据配置生成静态网页
将生成的文件推送到公开仓库
GitHub Pages 检测到文件变更, 自动更新你的博客

能否使用自定义域名?

Sure, 配置完成后,你可以在 GitHub Pages 的设置中绑定自己的域名

准备工作

在开始之前,请确保你已准备好:

✅ 一个 GitHub 账号
✅ Node.js 环境(推荐使用最新的 v22 LTS 版本)
✅ 代码编辑器(推荐 VS Code)
✅ Git 环境(方便提交代码到 Github 仓库)

注意事项

本文提到的「GitHub 用户名」均指你登录 GitHub 时的 username, 而非昵称

配置文件中的英文注释建议保留,有助于理解配置项含义

Step 1:本地安装与初始化

1.1 安装 Node.js

访问 Node.js 官网下载并安装最新的 LTS 版本(我使用的是 v22.14.0)

安装完成后,打开终端验证:

1 2	node -v # 应显示 v22.14.0 或类似版本号 npm -v # 应显示 npm 版本号

1.2 创建项目文件夹

在你喜欢的位置(路径最好不要包含中文, 玄学问题容易出bug)创建一个文件夹, 例如 Blog
然后用 VS Code 打开

1.3 安装 Hexo CLI

在 VS Code 终端中执行:

1	npm install -g hexo-cli

安装完成后验证:

1	hexo version

1.4 初始化 Hexo 项目

1 2	hexo init npm install

初始化完成后,项目目录结构大致如下:

Blog/
├── _config.yml       # 网站配置文件
├── source/           # 资源文件夹
│   └── _posts/       # Markdown 文章存放位置
├── themes/           # 主题文件夹
└── xxxx # 以及其他文件夹/文件, 此处不列举

1.5 配置网站 URL

编辑根目录下的 _config.yml 文件,找到 # URL 部分:

如果使用 GitHub Pages 默认域名:

1
2
3

# URL
## Set your site url here. For example, if you use GitHub Page, set url as 'https://username.github.io/project'
url: https://<你的GitHub用户名>.github.io/

将 <你的GitHub用户名> 替换为你的实际用户名,例如 https://gebilaowang.github.io/

如果使用自定义域名:

1
2
3

# URL
## Set your site url here. For example, if you use GitHub Page, set url as 'https://username.github.io/project'
url: https://your-domain.com/

1.6 本地预览

1	hexo s # 此处 s 是 server 的简写

终端应显示:

1
2
3

INFO  Validating config
INFO  Start processing
INFO  Hexo is running at http://localhost:4000/ . Press Ctrl+C to stop.

在浏览器中打开 http://localhost:4000/, 你应该能看到 Hexo 的页面了

Step 2:主题配置(可选)

Hexo 的默认主题比较简洁,如果你想要更美观的界面,可以安装第三方主题。

Step 3:创建 GitHub 仓库

3.1 创建私有仓库(存储源文件)

登录 GitHub,点击右上角的 + → New repository
仓库名称可以随意取,例如 hexo-blog 或 blog-source
重要: 选择 Private 私有仓库
不要初始化 README、.gitignore 或 license
点击 Create repository

3.2 创建公开仓库(托管网页)

再次点击 + → New repository
重要: 仓库名称必须严格按照格式 <你的GitHub用户名>.github.io
- 例如,如果你的用户名是 gebilaowang,则仓库名为 gebilaowang.github.io
- 大小写必须匹配你的用户名
选择 Public 公开仓库
点击 Create repository

为什么要创建两个仓库?

私有仓库保护你的源文件(配置、草稿等)不被公开

公开仓库只包含生成的静态文件, 符合 GitHub Pages 的要求

分离源码和产物, 便于维护

Step 4:配置 GitHub Actions 自动部署

4.1 创建工作流文件

打开项目根目录的 .github/workflows/ 文件夹(如果不存在请自行创建):

1	mkdir -p .github/workflows

在 .github/workflows/ 文件夹下创建 deploy.yml 文件, 内容如下:

name: Deploy to GitHub Pages

on:
  push:
    branches:
      - main  # 当推送到 main 分支时触发

jobs:
  deploy-gh-pages:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@master

      - name: Build and Deploy
        uses: theme-keep/hexo-deploy-github-pages-action@master
        env:
          BRANCH: main
          PUBLISH_DIR: ./public
          PERSONAL_TOKEN: ${{ secrets.HEXO_GHPAGE_SECRET }}
          PUBLISH_REPOSITORY: <你的GitHub用户名>/<你的GitHub用户名>.github.io

必须修改的地方:

将最后一行的 <你的GitHub用户名> 替换为你的实际用户名
例如: PUBLISH_REPOSITORY: gebilaowang/gebilaowang.github.io

4.2 生成 GitHub Personal Access Token

点击 GitHub 右上角头像 → Settings
左侧菜单滚动到底部,点击 Developer settings
展开 Personal access tokens → 点击 Tokens (classic)
点击右上角 Generate new token → 选择 Generate new token (classic)

配置 Token:

Note: 填写备注,例如 Hexo Deployment Token
Expiration: 选择 No expiration(永不过期)
权限勾选:
- ✅ repo (完整的仓库控制权限)
- ✅ workflow (更新 GitHub Action 工作流)

滚动到页面底部,点击 Generate token
重要: 立即复制生成的 Token(格式如 ghp_xxxxxxxxxxxx)

⚠️ 警告:
Token 只显示一次! 请立即保存到安全的地方, 丢失后需要重新生成
请勿泄露此 Token, 泄露 Token 有被他人盗用 Github 账号的风险!

4.3 配置仓库 Secret

打开你的 私有仓库(存储源文件的那个)
点击 Settings → 左侧 Secrets and variables → Actions
点击 New repository secret
填写:
- Name: HEXO_GHPAGE_SECRET (如果你自己改了名, 必须与 deploy.yml 中的变量名一致)
- Secret: 粘贴刚才复制的 Token
点击 Add secret

Step 5:推送代码并部署

5.1 初始化 Git 仓库

如果你的 VS Code 终端还在运行 hexo server, 先按 Ctrl+C 停止

1
2
3

git init
git add .
git commit -m "Initial commit: Hexo blog setup"

5.2 关联远程仓库

将本地仓库关联到你的私有仓库:

1	git remote add origin https://github.com/<你的GitHub用户名>/<私有仓库名>.git

例如:

1	git remote add origin https://github.com/gebilaowang/hexo-blog.git

5.3 推送到 GitHub

1 2	git branch -M main git push -u origin main

5.4 查看部署进度

推送完成后,打开你的私有仓库
点击顶部 Actions 标签
你应该能看到一个正在运行的工作流 Deploy to GitHub Pages
点击进去可以查看详细的构建日志
等待绿色的 ✅ 标志出现,表示部署成功

5.5 配置 GitHub Pages

打开你的 公开仓库(username.github.io)
此时仓库应该已经有文件了(由 Actions 自动推送)
点击 Settings → 左侧 Pages
Build and deployment 部分:
- Source: 选择 Deploy from a branch
- Branch: 选择 main 分支,目录保持 / (root)
点击 Save

5.6 访问你的博客

稍等 1-2 分钟,打开浏览器访问:

1	https://<你的GitHub用户名>.github.io/

如果出现了 Hexo 界面, 那么恭喜你

你的 Hexo 博客已经成功部署到 GitHub Pages 了

Step 6:日常写作流程

6.1 创建新文章

打开 VS Code 的终端, 执行:

1	hexo new "文章标题"

这会在 source/_posts/ 目录下生成一个新的 Markdown 文件

6.2 编辑文章

打开新生成的 Markdown 文件, 开始写作

示例:

---
title: My first blog
date: 2025-03-06 12:00:00
tags:
  - Essay
categories:
  - Daily
description: This is my first blog.
---

这里是正文内容...

6.3 本地预览

1
2
3

hexo clean  # 清除缓存
hexo generate  # 或 hexo g,生成静态文件
hexo server  # 或 hexo s,启动本地服务器

在浏览器中访问 http://localhost:4000/ 预览效果

6.4 发布更新

确认无误后,提交并推送到 GitHub:

1
2
3

git add .
git commit -m "docs: <新文章名称>" # 推荐在 commit 里注明新增的内容, 方便后续管理
git push

推送完成后, GitHub Actions 会进行如下操作:

检测到新的推送, 运行构建流程
生成静态文件
部署到 GitHub Pages

稍等片刻, 刷新你的博客页面, 新文章就会出现了

常见问题与解决方案

Q1: Actions 构建失败怎么办?

解决方案:

检查 deploy.yml 中的 PUBLISH_REPOSITORY 是否正确
确认 Token 权限是否勾选了 repo 和 workflow
查看 Actions 日志, 可 Google 搜索问题详情, 或使用 Coding AI 帮助定位具体错误信息

Q2: 推送后博客没有更新?

解决方案:

检查 Actions 是否运行成功(运行成功则左侧图标为绿色对勾✅)
清除浏览器缓存后刷新重试
编译出的静态网页有时需要几分钟才能全部部署到服务器上, 可耐心等待几分钟后重试

Q3: 如何绑定自定义域名?

如果你计划使用自定义域名,需要提前配置:

在私有仓库的 source/ 目录下创建 CNAME 文件(无扩展名)
文件内容为你的域名,例如:

1	blog.yourdomain.com

在域名服务商处添加 CNAME 记录,指向 username.github.io
等待 DNS 生效(可能需要几小时)

这样每次提交时, CNAME 文件会被复制到 public/ 目录, 然后随构建结果一起推送到公开仓库

注意: CNAME 文件内只能有一行,即你的域名,不要有多余的空行或内容

Q4: 主题配置修改后不生效?

解决方案:

1
2
3

hexo clean # 清除缓存
hexo generate # 重新生成
hexo server # 打开服务端, 浏览器查看是否生效

Q5: 如何备份博客?

几点建议如下:

可定期推送到其他 Git 平台, 如自建 Gitea
可以在其他设备或是 NAS 上保留几份副本
较为重要的配置文件建议单独备份

尾声

恭喜你, 你已经拥有了一个基于 Github Pages 的 Hexo 博客

接下来, 开始你的写作之旅吧!

参考资源

Author: MarchSnow

Link: https://blog.88889000.xyz/2026/tech/hexo-github-actions-github-pages/

Publish date: March 5th 2026, 20:34:20 UTC

Update date: March 7th 2026, 20:57:02 UTC

Page Views: --

License: Licensed under a Creative Commons Attribution-NonCommercial 4.0 International License.

Next Post

使用 GitHub No-Reply 邮箱, 为你的 Github 账户加一层隐私保护
Previous Post

Hello World

CATALOG

1. 前言
2. Step 1:本地安装与初始化
3. Step 2:主题配置(可选)
1. 3.1. 热门主题推荐
4. Step 3:创建 GitHub 仓库
1. 4.1. 3.1 创建私有仓库(存储源文件)
2. 4.2. 3.2 创建公开仓库(托管网页)
5. Step 4:配置 GitHub Actions 自动部署
6. Step 5:推送代码并部署
7. Step 6:日常写作流程
8. 常见问题与解决方案
9. 尾声
10. 参考资源

使用 GitHub Actions 在 GitHub Pages 上部署 Hexo 博客

前言

什么是 GitHub Pages?

什么是 Hexo?

工作原理

能否使用自定义域名?

准备工作

Step 1:本地安装与初始化

1.1 安装 Node.js

1.2 创建项目文件夹

1.3 安装 Hexo CLI

1.4 初始化 Hexo 项目

1.5 配置网站 URL

1.6 本地预览

Step 2:主题配置(可选)

热门主题推荐

Step 3:创建 GitHub 仓库

3.1 创建私有仓库(存储源文件)

3.2 创建公开仓库(托管网页)

Step 4:配置 GitHub Actions 自动部署

4.1 创建工作流文件

4.2 生成 GitHub Personal Access Token

4.3 配置仓库 Secret

Step 5:推送代码并部署

5.1 初始化 Git 仓库

5.2 关联远程仓库

5.3 推送到 GitHub

5.4 查看部署进度

5.5 配置 GitHub Pages

5.6 访问你的博客

Step 6:日常写作流程

6.1 创建新文章

6.2 编辑文章

6.3 本地预览

6.4 发布更新

常见问题与解决方案

Q1: Actions 构建失败怎么办?

Q2: 推送后博客没有更新?

Q3: 如何绑定自定义域名?

Q4: 主题配置修改后不生效?

Q5: 如何备份博客?

尾声

参考资源