使用 Gitea Actions 自动部署 Hexo 博客到 Cloudflare Pages

8.0k 字 约 27 分钟

前言

在搭建个人博客时，自动化部署可以大大简化发布流程。本文将详细介绍如何使用 Gitea Actions 自动构建 Hexo 博客并部署到 Cloudflare Pages，实现推送代码即可自动更新网站。

为什么选择 Cloudflare Pages？

Cloudflare Pages 是一个优秀的静态网站托管平台，具有以下优势：

  • 全球 CDN 加速：网站内容分发到全球 200+ 节点
  • 自动 HTTPS：免费 SSL 证书，自动配置
  • 快速部署：支持多种构建工具，部署速度快
  • 自定义域名：支持绑定多个域名
  • 免费额度充足：对于个人博客完全够用
  • CNAME 拉平：根域名可以使用 CNAME，解决与 MX 记录冲突问题

整体流程

整个自动化部署流程如下：

1
2
本地编写文章 → git push 到 Gitea → Gitea Actions 触发 → 
安装依赖 → hexo generate → wrangler deploy → Cloudflare Pages 更新

准备工作

1. 创建 Hexo 博客项目

首先初始化一个 Hexo 博客：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 安装 Hexo CLI
npm install hexo-cli -g

# 创建博客项目
hexo init my-blog
cd my-blog

# 安装依赖
npm install

# 安装主题（示例使用 starter 主题）
git clone https://github.com/nijich/hexo-theme-starter.git themes/starter

# 修改 _config.yml 使用主题
theme: starter

2. 配置博客基本信息

编辑 _config.yml：

1
2
3
4
5
6
7
8
9
10
11
# Site
title: My Blog
subtitle: '技术探索与生活记录'
description: '个人技术博客'
author: Your Name
language: zh-CN
timezone: 'Asia/Shanghai'

# URL（填写最终部署的域名）
url: https://blog.example.com
permalink: :year/:month/:day/:title/

3. 创建 Gitea 仓库

在自建的 Gitea 服务器上创建仓库，例如：

1
2
3
4
5
6
7
8
9
10
# 初始化本地仓库
git init

# 提交代码
git add .
git commit -m "Initial commit"

# 连接远程仓库
git remote add origin https://gitea.example.com/username/blog.git
git push -u origin main

配置 Gitea Actions

创建 Workflow 文件

在项目根目录创建 .gitea/workflows/deploy.yml：

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
name: Deploy Blog to Cloudflare Pages

on:
  push:
    branches:
      - main
  workflow_dispatch:

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

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

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

      - name: Generate Blog
        run: |
          hexo clean
          hexo generate

      - name: Install wrangler
        run: npm install -g wrangler

      - name: Create Cloudflare Pages project
        run: wrangler pages project create blog --production-branch main || true
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

      - name: Deploy to Cloudflare Pages
        run: wrangler pages deploy public --project-name=blog --commit-dirty=true
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

Workflow 步骤详解

触发条件：

1
2
3
4
5
on:
  push:
    branches:
      - main
  workflow_dispatch:
  • push：推送代码到 main 分支时自动触发
  • workflow_dispatch：支持在 Gitea Actions 页面手动触发

Checkout 步骤：

1
2
- name: Checkout
  uses: actions/checkout@v4

使用官方 checkout action 拉取仓库代码。

安装 Node.js：

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

安装 Node.js 20 版本，Hexo 需要 Node 环境。

安装依赖：

1
2
3
4
- name: Install Dependencies
  run: |
    npm install hexo-cli -g
    npm install

全局安装 Hexo CLI，然后安装项目依赖（package.json 中定义的）。

生成静态文件：

1
2
3
4
- name: Generate Blog
  run: |
    hexo clean
    hexo generate

hexo clean 清理旧的构建文件，hexo generate 生成静态文件到 public 目录。

安装 Wrangler：

1
2
- name: Install wrangler
  run: npm install -g wrangler

Wrangler 是 Cloudflare 的官方 CLI 工具，用于部署到 Cloudflare Pages。

创建 Pages 项目：

1
2
- name: Create Cloudflare Pages project
  run: wrangler pages project create blog --production-branch main || true

创建名为 blog 的 Pages 项目。|| true 表示如果项目已存在则忽略错误继续执行。

部署到 Cloudflare：

1
2
- name: Deploy to Cloudflare Pages
  run: wrangler pages deploy public --project-name=blog --commit-dirty=true

将 public 目录部署到 blog 项目。--commit-dirty=true 参数很重要，因为：

  • Actions checkout 后仓库是干净状态
  • hexo generate 生成的 public 目录是新文件，不在 git 中
  • wrangler 默认要求部署内容在 git 中，需要这个参数来处理未追踪文件

配置 Secrets

在 Gitea 仓库中添加 Secrets：

  1. 进入仓库 Settings → Secrets 页面
  2. 添加两个 secrets：

CLOUDFLARE_API_TOKEN

获取方式：

  • 登录 Cloudflare Dashboard
  • 进入 My Profile → API Tokens
  • 点击 “Create Token”
  • 选择 “Edit Cloudflare Pages” 模板，或自定义权限：
    • Account → Cloudflare Pages → Edit
  • 复制生成的 token

CLOUDFLARE_ACCOUNT_ID

在 Cloudflare Dashboard 右侧边栏可以看到 Account ID，是一串 32 位字符。

绑定自定义域名

部署成功后，博客会发布到 Cloudflare Pages 提供的默认域名，类似：

1
https://blog-xxx.pages.dev

添加自定义域名

在 Cloudflare Dashboard 中操作：

  1. 登录 https://dash.cloudflare.com
  2. 进入 Pages → 选择 blog 项目
  3. 点击 “Custom domains” 标签页
  4. 点击 “Set up a custom domain”
  5. 输入域名，例如：blog.example.com
  6. 保存

DNS 配置

如果域名已在 Cloudflare，DNS 会自动配置：

  • 记录类型：CNAME
  • 名称：blog
  • 目标：blog-xxx.pages.dev
  • 代理状态：已代理（橙色云朵图标）

Cloudflare 会启用 CNAME 拉平（CNAME Flattening）：

  • DNS 查询返回的是真实 IP（A 记录），而不是 CNAME
  • 解决根域名 CNAME 与 MX 记录冲突的问题
  • 目标 IP 变化时，Cloudflare 自动更新

如果域名不在 Cloudflare，需要在域名服务商处添加 CNAME 记录指向 Pages 的域名。

优化构建速度

添加依赖缓存

1
2
3
4
5
6
7
8
9
10
11
12
- name: Cache node modules
  uses: actions/cache@v3
  with:
    path: node_modules
    key: ${{ runner.os }}-node-${{ hashFiles('package-lock.json') }}
    restore-keys: |
      ${{ runner.os }}-node-

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

缓存 node_modules 可以显著加快后续构建速度，从几分钟缩短到几秒。

并行处理

如果博客文章很多，可以考虑：

1
2
- name: Generate Blog
  run: hexo generate --bail

--bail 参数在遇到错误时立即停止，方便排查问题。

常见问题

Q: Actions 执行失败，提示找不到 secrets

原因：Secrets 没有正确配置。

解决：

  1. 检查 Gitea 仓库的 Settings → Secrets
  2. 确保 CLOUDFLARE_API_TOKEN 和 CLOUDFLARE_ACCOUNT_ID 都已添加
  3. Secrets 的名称必须与 workflow 中的引用一致

Q: hexo generate 报错

原因：可能是主题配置问题或文章格式错误。

解决：

  1. 查看 Actions 日志中的错误信息
  2. 本地执行 hexo generate 测试
  3. 检查主题配置文件 _config.theme.yml
  4. 检查文章的 front-matter 格式是否正确

Q: 部署成功但网站空白

原因：public 目录没有正确生成。

解决：

  1. 检查 Actions 日志，确认 hexo generate 成功
  2. 确认 public 目录中有 index.html
  3. 检查主题是否正确安装

Q: wrangler 报错 “ENOENT: no such file or directory”

原因：部署目录不存在或路径错误。

解决：

  1. 确保 hexo generate 已执行
  2. 检查 public 目录是否存在
  3. 使用正确的路径参数：wrangler pages deploy public

Q: 如何手动触发部署？

在 Gitea 仓库中：

  1. 进入 Actions 页面
  2. 选择 “Deploy Blog to Cloudflare Pages” workflow
  3. 点击 “Run workflow” 按钮
  4. 选择分支（默认 main）后确认

高级配置

多环境部署

可以配置开发环境和生产环境：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
jobs:
  deploy-production:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      # ... 构建步骤
      - name: Deploy to Production
        run: wrangler pages deploy public --project-name=blog

  deploy-staging:
    if: github.ref == 'refs/heads/develop'
    runs-on: ubuntu-latest
    steps:
      # ... 构建步骤
      - name: Deploy to Staging
        run: wrangler pages deploy public --project-name=blog-staging

这样推送到不同分支会部署到不同的 Pages 项目。

部署通知

添加部署成功/失败的通知：

1
2
3
4
5
6
7
8
9
10
- name: Notify on Success
  if: success()
  run: echo "Deploy success! Blog is live at https://blog.example.com"

- name: Notify on Failure
  if: failure()
  run: |
    # 可以发送 webhook、邮件等通知
    curl -X POST "${{ secrets.NOTIFICATION_URL }}" \
      -d '{"text": "Blog deployment failed"}'

自动创建文章

可以在 workflow 中添加自动创建文章的步骤（适合定时发布）：

1
2
3
4
- name: Create scheduled post
  run: |
    # 根据时间或其他条件创建文章
    hexo new post "$(date +%Y-%m-%d)-daily-update"

最佳实践

1. 使用主题配置文件

不要直接修改 themes/theme-name/_config.yml，而是在根目录创建 _config.theme-name.yml：

1
cp themes/starter/_config.yml _config.starter.yml

这样：

  • 主题可以作为 submodule 或直接克隆
  • 配置不会因为主题更新而丢失
  • 更符合 Hexo 的最佳实践

2. 管理主题为 submodule

1
2
3
4
5
# 删除直接克隆的主题
rm -rf themes/starter

# 添加为 submodule
git submodule add https://github.com/nijich/hexo-theme-starter.git themes/starter

好处：

  • 主题更新时只需更新 submodule
  • 主题版本可控
  • 不会意外修改主题文件

3. 忽略不必要的文件

编辑 .gitignore：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 构建输出
public/

# 依赖
node_modules/

# Hexo 临时文件
.db.json

# 日志
*.log

# wrangler 状态
.wrangler/

4. 定期更新依赖

1
2
3
4
- name: Check for updates
  run: |
    npm outdated
    # 可以添加自动更新逻辑

总结

通过 Gitea Actions 自动部署 Hexo 博客到 Cloudflare Pages，实现了：

  • 自动化：推送代码即可部署，无需手动操作
  • 高效：全球 CDN 加速，访问速度快
  • 可靠：每次部署都有日志，易于排查问题
  • 灵活：支持自定义域名、多环境部署

整个配置过程主要包括：

  1. 初始化 Hexo 博客项目
  2. 创建 Gitea 仓库并推送代码
  3. 编写 Gitea Actions workflow
  4. 配置 Cloudflare API Token
  5. 在 Cloudflare Dashboard 绑定域名

这套方案适用于任何自建 Gitea 服务器，结合 Cloudflare Pages 的强大功能，可以轻松搭建高性能的个人博客。

参考资源

Hexo Cloudflare Gitea Actions CI/CD 自动化部署

本文作者：Nival

本文链接：https://blog.nival.dev/2026/05/10/%E4%BD%BF%E7%94%A8-Gitea-Actions-%E8%87%AA%E5%8A%A8%E9%83%A8%E7%BD%B2-Hexo-%E5%8D%9A%E5%AE%A2%E5%88%B0-Cloudflare-Pages/

版权声明：本博客所有文章除特别声明外，均采用 CC BY-NC-SA 4.0 许可协议。转载请注明出处！

ESC 关闭 | ↑↓ 导航 | Enter 打开
输入关键词开始搜索
Ctrl + K 快速搜索