前言

在众多静态博客生成器中，Hugo 以其极快的构建速度和简洁的配置脱颖而出。结合 Cloudflare Pages 的全球 CDN，你可以获得一个完全免费、高速可靠的个人博客。本教程将手把手带你完成整个搭建过程。

基础准备

需要准备的账户

1. GitHub 账号 - 代码托管
2. Cloudflare 账号 - 免费部署平台

本地环境（可选）

• Git
• Hugo（如果要在本地写作）

第一步：创建 Hugo 项目

方法A：本地创建（推荐）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# 安装 Hugo（以 macOS 为例）
brew install hugo

# 创建新站点
hugo new site my-blog
cd my-blog

# 添加主题（以 Paper 主题为例）
git submodule add https://github.com/nanxiaobei/hugo-paper themes/paper
echo "theme = 'paper'" >> hugo.toml

方法B：直接使用模板

1. 访问 Hugo Themes
2. 找到喜欢的主题，点击 “Download” 获取 GitHub 链接
3. Fork 到自己的账户

第二步：配置 GitHub 仓库

创建新仓库

1. 登录 GitHub，点击右上角 “+” → “New repository”
2. 仓库名：my-hugo-blog
3. 选择 “Public”
4. 不要初始化 README、.gitignore 或 license

推送代码到 GitHub

1
2
3
4
5
6
7

# 如果是本地创建的 Hugo 项目
git init
git add .
git commit -m "Initial commit"
git branch -M main
git remote add origin https://github.com/你的用户名/my-hugo-blog.git
git push -u origin main

第三步：Cloudflare Pages 部署

1. 连接 GitHub

1. 登录 Cloudflare Dashboard
2. 左侧菜单选择 “Workers & Pages” → “Create application” → “Pages” → “Connect to Git”

2. 配置构建设置

• 选择仓库：选择你的 my-hugo-blog 仓库
• 生产分支：main
• 构建设置：
  • Build command: hugo
  • Build output directory: public
• 环境变量（高级设置）：
  • HUGO_VERSION: 0.125.0（与你本地版本一致）

3. 开始部署

点击 “Save and Deploy”，等待 2-3 分钟完成首次构建。

第四步：撰写和发布内容

创建文章

在 GitHub 上直接操作：

1. 进入仓库 → content/posts/ 目录
2. 点击 “Add file” → “Create new file”
3. 文件名：posts/我的第一篇文章.md
4. 内容：

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

---
title: "我的第一篇文章"
date: 2024-11-21
draft: false
tags: ["教程", "Hugo"]
categories: ["技术"]
---

## 欢迎阅读！

这是我的第一篇 Hugo 博客文章。

### 功能特点
- ⚡ 极速构建
- 🌍 全球 CDN 加速
- 💯 完全免费
- 📱 响应式设计

感谢 Cloudflare Pages 提供的出色服务！

文章 Front Matter 详解

1
2
3
4
5
6
7
8

---
title: "文章标题"          # 必填
date: 2024-11-21           # 必填，发布时间
draft: false               # 是否为草稿
tags: ["标签1", "标签2"]   # 文章标签
categories: ["分类"]       # 文章分类
description: "文章描述"    # 可选，文章摘要
---

第五步：自定义域名

添加自定义域名

1. 在 Cloudflare Pages 项目页面
2. 点击 “Custom domains” → “Set up a custom domain”
3. 输入你的域名：blog.yourdomain.com

DNS 配置

在域名服务商处添加 CNAME 记录：

• 类型: CNAME
• 名称: blog
• 目标: your-project.pages.dev（Cloudflare 提供的域名）
• TTL: 自动

🚨 常见问题与解决方案

1. 构建失败：“Hugo command not found”

问题：Cloudflare 找不到 Hugo 解决：在环境变量中设置 HUGO_VERSION

2. 页面空白或样式丢失

问题：baseURL 配置错误 解决：在 hugo.toml 中设置：

1

baseURL = "https://你的域名.com"

3. 文章不显示

问题：首页模板未正确配置 解决：确保 layouts/index.html 包含：

1
2
3

{{ range .Site.RegularPages }}
  <a href="{{ .Permalink }}">{{ .Title }}</a>
{{ end }}

4. 图片不显示

问题：图片路径错误 解决：

• 图片放在 static/images/ 目录
• 文章中引用：![描述](/images/图片名.jpg)

5. 自定义主题不生效

问题：主题未正确引用 解决：在 hugo.toml 中确认：

1

theme = "你的主题名称"

高级配置

1. 自动构建触发

每次向 GitHub 推送代码时，Cloudflare Pages 会自动重新部署。你也可以手动触发：

• Pages 项目页面 → “Trigger deployment”

2. 环境变量管理

• HUGO_ENVIRONMENT: production
• HUGO_ENABLEGITINFO: true

3. 自定义构建命令

1

hugo --minify --cleanDestinationDir

最佳实践

写作工作流

1. 本地写作（可选）：

   1 2	hugo new posts/文章标题.md hugo server -D # 本地预览

2. 在线编辑：

   • 直接通过 GitHub 网页界面编辑
   • 提交后自动部署

版本控制策略

• 每篇文章一个 commit
• 清晰的 commit 信息
• 定期备份重要内容

性能优化

• 图片压缩后再上传
• 使用 Hugo 内置的 minify 功能
• 利用 Cloudflare 的缓存功能

成本分析

结语

通过本教程，你已经成功搭建了一个：

• ✅ 完全免费的博客系统
• ✅ 全球加速的访问体验
• ✅ 自动部署的发布流程
• ✅ 版本控制的内容管理
• ✅ 专业域名的个性化展示

现在，开始你的博客之旅吧！每次内容更新只需在 GitHub 上点击几次，2分钟后全球读者就能看到最新内容。

技术不应该成为表达的门槛 - 让 Cloudflare Pages + Hugo 帮你专注于创作本身。

教程更新时间：2024年11月
适用版本：Hugo 0.125+, Cloudflare Pages 最新版