前言

一直想搭个自己的博客，记录一些技术思考和随笔杂记。要求很简单：

  • 📝 写 Markdown 就行，别折腾
  • 🆓 全程免费，不花一分钱
  • 🚀 推送代码后自动部署
  • 🌙 支持暗黑模式、代码高亮、目录
  • 🏷️ 支持标签、分类、RSS

最终选了 Hugo + PaperMod + Cloudflare Pages + GitHub Actions 这套方案。下面是完整过程。

技术选型

对比了几个主流方案：

框架构建速度部署难度主题生态推荐度
Hugo⚡ 极快简单丰富⭐⭐⭐⭐⭐
Astro快简单增长中⭐⭐⭐⭐
Hexo中简单丰富⭐⭐⭐⭐
Jekyll慢简单丰富⭐⭐⭐

最终选 Hugo：单二进制零依赖，构建秒级完成，PaperMod 主题开箱即用。

整体工作流

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

本地写 Markdown 文章
        ↓
git push 到 GitHub (main 分支)
        ↓
GitHub Actions 自动触发
        ↓
构建 Hugo 静态资源
        ↓
自动部署到 Cloudflare Pages
        ↓
网站更新完成 ✅

全程自动化，你只需要写文章 + push。

项目结构

1
2
3
4
5
6
7
8
9

my-blog/
├── .github/workflows/deploy.yml    # CI/CD 配置
├── archetypes/default.md           # 文章模板
├── content/posts/                  # 📝 博客文章
│   └── hello-world/index.md
├── themes/PaperMod/                # 主题 (git submodule)
├── static/                         # 静态资源
├── hugo.toml                       # ⭐ Hugo 主配置
└── .gitignore

Hugo 配置要点

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

baseURL = 'https://xiaohuang-blog.pages.dev'
languageCode = 'zh-CN'
title = '小黄的博客'
theme = 'PaperMod'

[params]
  author = '小黄'
  description = '记录一些自己的思考，随笔杂记'
  defaultTheme = 'auto'          # 自动暗黑模式
  ShowToc = true                  # 显示目录
  ShowCodeCopyButtons = true      # 代码复制按钮

[taxonomies]
  category = 'categories'
  tag = 'tags'

[outputs]
  home = ['HTML', 'RSS', 'JSON']  # RSS 订阅支持

GitHub Actions 配置

.github/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

name: Build & Deploy to Cloudflare Pages

on:
  push:
    branches: [main]

permissions:
  contents: read
  deployments: write

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          submodules: true
          fetch-depth: 0

      - uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: '0.166.0'
          extended: true

      - run: hugo --minify

      - uses: cloudflare/pages-action@v1
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          projectName: ${{ secrets.CLOUDFLARE_PROJECT_NAME }}
          directory: ./public

踩坑记录

1. 子模块问题

第一次 push 后 Actions 报错 No url found for submodule path，原因是没有 .gitmodules 文件。解决方法：

1
2
3
4

# 创建 .gitmodules
[submodule "themes/PaperMod"]
    path = themes/PaperMod
    url = https://github.com/adityatelange/hugo-PaperMod.git

2. Cloudflare Pages 域名问题

Wrangler 新版默认部署到 Workers 平台，域名是 .workers.dev（国内访问不了）。想要 .pages.dev 需要通过 API 直接创建传统 Pages 项目：

1
2
3

curl -X POST "https://api.cloudflare.com/client/v4/accounts/{account_id}/pages/projects" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"name":"xiaohuang-blog","production_branch":"main"}'

3. OAuth 无法创建 API Token

Wrangler 的 OAuth Token 权限有限，无法通过 API 创建新 Token。需要在 Cloudflare Dashboard 手动创建 API Token：

  • 权限：Account → Cloudflare Pages → Edit

日常使用

1
2
3
4
5
6
7
8

# 新建文章
hugo new content/posts/文章标题/index.md

# 本地预览
hugo server -D

# 提交推送（自动触发部署）
git add . && git commit -m "post: xxx" && git push

总结

整套方案：

  • ✅ 免费：GitHub + Cloudflare Pages 免费额度足够
  • ✅ 自动化：push 即部署
  • ✅ 功能全：暗黑模式、代码高亮、TOC、标签、RSS
  • ✅ 维护低：写 Markdown 即可，主题可替换

如果你也想搭博客，可以直接用这套方案 👆