1. 方案概述
| 组件 | 用途 |
|---|---|
| Cloudflare Pages | 静态网站托管（全球 CDN、免费无限带宽） |
| Hugo | 静态网站生成器（Markdown → HTML） |
| Wrangler | Cloudflare CLI 工具（本地部署） |
工作流：本地写 Markdown → Hugo 构建 → Wrangler 部署 → 上线
2. 安装 Hugo
安装 Hugo
在这个网页获取hugo的最新安装版本，注意是要extended的，避免一些主题不支持：
https://github.com/gohugoio/hugo/releases
因为我是wsl2的环境（推荐），当前我选择：
https://github.com/gohugoio/hugo/releases/download/v0.159.0/hugo_extended_0.159.0_linux-arm64.deb
# Ubuntu/WSL - 安装最新版
wget https://github.com/gohugoio/hugo/releases/download/v0.159.0/hugo_extended_0.159.0_linux-arm64.deb
sudo dpkg -i hugo_extended_0.159.0_linux-arm64.deb
# 验证
hugo version
创建新站点
# 创建站点
hugo new site my-blog
cd my-blog
# 初始化 Git 仓库
git init
基础配置 (hugo.toml)
baseURL = 'https://your-domain.pages.dev' # 需要注意的是，后续一定要修改过来，否则文章点击跳转不到文章
languageCode = 'zh-CN'
title = '我的技术博客'
theme = 'PaperMod'
[params]
author = '你的名字'
description = '分享技术、记录成长'
ShowReadingTime = true
ShowShareButtons = true
ShowPostNavLinks = true
[menu]
[[menu.main]]
identifier = 'posts'
name = '文章'
url = '/posts/'
weight = 10
[[menu.main]]
identifier = 'tags'
name = '标签'
url = '/tags/'
weight = 20
[[menu.main]]
identifier = 'about'
name = '关于'
url = '/about/'
weight = 30
3. 安装 Wrangler
npm install -g wrangler
# 验证
wrangler --version
Wrangler 部署到 Cloudflare Pages 时，不同 branch 的行为差异如下：
Branch 类型与部署行为
| Branch | 部署结果 | 访问 URL | 用途 |
|---|---|---|---|
main / master |
生产环境 | https://your-project.pages.dev |
正式站点 |
其他分支 (如 dev, feature-x) |
预览环境 | https://[branch-name].your-project.pages.dev |
测试/预览 |
具体示例
# 当前在 main 分支
git checkout main
wrangler pages deploy public
# 结果: 部署到生产环境 https://my-blog.pages.dev
# 切换到 dev 分支
git checkout -b dev
# 修改内容...
wrangler pages deploy public
# 结果: 部署到预览环境 https://dev.my-blog.pages.dev
关键特性
1. 预览部署（非 main 分支）
- 自动生成唯一 URL
- 不影响生产环境
- 适合代码审查、内容预览
- 支持密码保护（可在 Cloudflare Dashboard 设置）
2. 生产部署（main/master）
- 部署到主域名
- 触发自动构建（如绑定了 Git）
- 可配置自定义域名
常用工作流
# 1. 开发新功能
git checkout -b feature/new-post
# 编辑内容...
wrangler pages deploy public
# 获得预览链接: https://feature-new-post.my-blog.pages.dev
# 2. 分享给团队/朋友预览
# 发送预览链接，确认无误后...
# 3. 合并到主分支
git checkout main
git merge feature/new-post
wrangler pages deploy public
# 正式环境更新
Git 集成 vs Wrangler 手动部署
| 方式 | Branch 行为 |
|---|---|
| Git 集成（推荐） | 自动部署：push 到 main → 生产；push 到其他分支 → 预览 |
| Wrangler CLI | 手动指定：当前 branch 决定部署目标 |
强制指定分支（高级）
# 无论当前 git branch 是什么，强制作为特定分支部署
wrangler pages deploy public --branch=main # 强制生产
wrangler pages deploy public --branch=preview # 强制预览
场景建议
作为技术博客，推荐 Git 集成 工作流：
- GitHub/GitLab 连接 Cloudflare Pages
- Push 到
main→ 自动生产部署 - Push 到
draft→ 自动预览部署（不公开）
这样无需手动运行 wrangler，且预览链接可分享审稿。
4. 获取 API Token
- 访问
https://dash.cloudflare.com/profile/api-tokens - Create Token → Custom token
- 权限设置：
| 权限 | 设置 | 中文界面 |
|---|---|---|
| Account | Cloudflare Pages | Cloudflare Pages |
| User | User Details | 用户详细信息 |
| User | Memberships | 成员资格 |
- 复制 Token
5. 验证 Token
export CLOUDFLARE_API_TOKEN=你的Token
wrangler whoami
成功显示账户信息即有效。
6. 安装主题
# 进入博客目录
cd 你的博客目录
# 添加 PaperMod 主题
git init
git submodule add --depth=1 https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod
# 启用主题（已在 hugo.toml 中设置 theme = 'PaperMod'）
7. 更新文章
创建新文章
hugo new content/posts/文章名.md
文章模板格式
---
title: "文章标题"
date: 2026-03-25T00:21:00+08:00
draft: false
tags: ["标签1", "标签2"]
categories: ["分类"]
description: "文章摘要"
---
正文内容，支持 **Markdown** 语法。
## 二级标题
- 列表项
- 列表项
本地预览
hugo server -D
# 访问 http://localhost:1313
部署
hugo && wrangler pages deploy public --project-name=你的项目名
8. 便捷写作模板
创建 archetypes/default.md（新建文章自动套用）：
---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
draft: true
tags: []
categories: []
description: ""
---
## 引言
<!-- 简介 -->
## 正文
<!-- 主要内容 -->
## 总结
<!-- 结论 -->
---
**参考链接**
-
9. Hugo 图片管理方式
方式1：Page Bundles（推荐 ⭐）
这是 Hugo 0.32+ 引入的最佳实践，将文章和相关资源放在同一文件夹。
content/
└── posts/
└── my-article/ ← 文件夹（不再是 .md 文件）
├── index.md ← 文章主体
├── image1.png ← 图片放在同目录
├── diagram.jpg
└── screenshot.png
markdown 中引用：
<!-- 相对路径引用 -->
<!-- 或使用 Hugo 的 figure 短代码 -->
系统架构图
方式2：静态资源文件夹
适合全局共享的图片（如 Logo、头像、公共图表）：
static/
├── images/
│ ├── logo.png
│ ├── avatar.jpg
│ └── common/
│ └── workflow.png
└── favicon.ico
markdown 中引用：
<!-- 路径从 static 开始算 -->
方式3：Assets 文件夹（需要处理）
适合需要 Hugo 处理的图片（压缩、调整大小）：
assets/
└── images/
└── photo.jpg
需要使用 Hugo 的资源处理功能，配合 resources.Get 使用。
推荐工作流
作为技术博客，建议这样组织：
content/
├── posts/
│ └── 2026/
│ └── 03-embedded-system/ # 文章 bundle
│ ├── index.md
│ ├── hardware-setup.jpg
│ └── debug-screenshot.png
└── about/
├── index.md
└── profile-photo.jpg # 个人照片
static/
└── images/
├── site-logo.png # 站点 Logo
└── common-icons/ # 通用图标
总结：
- 文章专属图片 → 用 Page Bundles（同文件夹）
- 站点共享图片 → 放
static/images/ - 需要处理的图片 → 放
assets/（高级用法）
10. 完整工作流总结
| 步骤 | 命令/操作 |
|---|---|
| 新建文章 | hugo new content/posts/xxx.md |
| 本地编辑 | 用 VS Code/Typora/Obsidian |
| 本地预览 | hugo server |
| 构建 | hugo |
| 部署 | wrangler pages deploy public --project-name=xxx |
Windows 一键脚本（deploy.bat）：
@echo off
hugo && wrangler pages deploy public --project-name=xxx