Hexo + GitHub Actions 搭建个人博客（2026 完整实战指南）

从零开始，到自动部署、自定义域名、Cloudflare、换电脑迁移、常见报错排查，一篇讲清楚。

---

一、为什么用 Hexo + GitHub Actions？

• ✅ 免费
• ✅ 全自动部署
• ✅ 不需要服务器
• ✅ 支持自定义域名 + HTTPS
• ✅ 支持 Cloudflare CDN
• ✅ 可多设备协作

推荐架构（2026 官方方式）：

main 分支：Hexo 源码
GitHub Actions：自动构建
GitHub Pages：自动发布

不再需要 gh-pages 分支，不再手动 push public。

---

二、初始化 Hexo 项目

1️⃣ 安装环境

• Node.js 推荐：Node 20
• Git

检查：

node -v
npm -v
git --version

---

2️⃣ 创建 Hexo 项目

npm install -g hexo-cli
hexo init myBlog
cd myBlog
npm install

测试：

npx hexo s

浏览器打开：

http://localhost:4000

---

三、创建 GitHub 仓库

创建仓库：

username.github.io

⚠️ 免费账号必须是 Public 才能使用 Pages。

---

四、把 Hexo 源码推送到 GitHub

在 Hexo 根目录执行：

git init
git add .
git commit -m "initial hexo source"
git branch -M main
git remote add origin git@github.com:username/username.github.io.git
git push -u origin main

---

五、启用 GitHub Actions 自动部署

进入仓库：

Settings → Pages

如果页面只显示域名选项，不要慌，这是新版 UI。

---

创建工作流文件

新建文件：

.github/workflows/pages.yml

内容如下（2026 官方推荐模板）：

name: Deploy Hexo to GitHub Pages

on:
  push:
    branches:
      - main
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm

      - name: Install Dependencies
        run: npm ci

      - name: Install Hexo CLI
        run: npm install -g hexo-cli

      - name: Build Hexo
        run: npx hexo generate

      - name: Setup Pages
        uses: actions/configure-pages@v4

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./public

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    runs-on: ubuntu-latest
    needs: build

    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

提交并 push：

git add .
git commit -m "add pages workflow"
git push

然后进入：

Actions

查看是否自动运行。

---

六、以后如何发布文章？

hexo new "新文章"
git add .
git commit -m "add post"
git push

自动完成：

• 安装依赖
• 生成 public
• 发布到 GitHub Pages

不再使用：

hexo deploy

---

七、换电脑如何继续写博客？

1️⃣ 克隆仓库

git clone git@github.com:username/username.github.io.git
cd username.github.io

2️⃣ 安装依赖

npm install

3️⃣ 本地测试

npx hexo s

---

⚠️ 前提：仓库中必须存放的是 Hexo 源码，而不是 public 静态文件。

---

八、如果之前 main 存的是 public 静态文件怎么办？

迁移步骤：

1. 备份当前静态文件到新分支：

git checkout -b backup-static
git push origin backup-static

2. 清空 main：

git checkout main
git rm -r *
git commit -m "clean branch"
git push

3. 推送 Hexo 源码到 main

4. 添加 GitHub Actions 工作流

---

九、自定义域名 + Cloudflare 配置

推荐结构

example.com        → A 记录
www.example.com    → CNAME

---

根域名必须添加 4 条 A 记录

185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

Cloudflare 设置：

• 类型：A
• 名称：@
• 代理：DNS only（灰色云）

⚠️ 不能只写一条。

---

www 使用 CNAME

CNAME www → username.github.io

---

Enforce HTTPS 无法勾选？

常见原因：

• Cloudflare 开了橙色云代理
• DNS 未指向 GitHub
• 证书还未签发

解决：

• 改为 DNS only
• 等 10~30 分钟
• 再刷新 GitHub Pages 页面

---

总结

Hexo + GitHub Actions 是目前：

• 最干净
• 最现代
• 最稳定
• 最低成本

的个人博客方案。

发布流程极简：

写文章 → git push → 自动部署

---