Cloudflare 免费部署 Hugo 博客 + 自定义域名 + R2 图床完整教程

本教程从零开始，带你使用 Cloudflare 全套服务搭建完全免费的个人博客：基于 Hugo 生成静态站点，Cloudflare Pages 托管网站并实现代码推送自动更新，Cloudflare R2 作为图片存储图床，全程零成本，自带全球 CDN 加速与免费 SSL 证书。

一、前期准备

1.1 所需账号与资源

GitHub 账号：存放 Hugo 源码，触发 Cloudflare Pages 自动构建
Cloudflare 账号：提供 Pages 托管、R2 存储、CDN 加速、SSL 证书等全部服务
（可选）自定义域名：用于绑定博客与图床，体验更佳；无域名可使用 Pages 和 R2 自带的免费子域名

1.2 注册 Cloudflare 账号

Cloudflare 提供完全免费的 Pages 托管与 R2 存储，无需绑定信用卡即可使用全部功能。

打开 https://dash.cloudflare.com/sign-up，输入邮箱和密码，点击「Sign Up」
注册完成后会自动进入 Cloudflare 控制台仪表盘，左侧菜单可看到 Workers & Pages、R2 等入口
首次登录建议完成人机验证（CAPTCHA），避免后续操作被风控拦截

如果已有 Cloudflare 账号，直接登录即可，无需重复注册。个人用户免费套餐已包含本教程所需的全部功能。

1.3 安装 Hugo

Hugo 支持 Windows、macOS、Linux 三大平台，推荐使用包管理器安装，方便后续升级。务必安装 Hugo Extended（扩展版），绝大多数主流主题依赖 SCSS/Sass 编译，普通版无法正常构建。

Windows

推荐使用 winget 一键安装，管理员权限打开终端执行：

1

winget install Hugo.Hugo.Extended

安装完成后重新打开终端，验证是否成功：

1

hugo version

输出示例：hugo v0.143.1+extended+withdeploy windows/amd64 ...

注意输出中必须包含 extended 字样，否则安装的是普通版，主题可能编译失败。

备用方式：到 Hugo GitHub Releases 页面，下载 Windows 平台文件名含 extended 的 .zip 包，解压后将 hugo.exe 所在目录添加到系统 PATH 环境变量。

macOS

使用 Homebrew 安装：

1
2
3


brew install hugo
# 验证安装
hugo version

Homebrew 默认安装的就是扩展版，输出中会包含 extended 标识。

Linux

以 Debian/Ubuntu 为例，通过 apt 安装扩展版：

1
2
3
4
5


# 添加 Hugo 官方源
curl -s https://api.github.com/repos/gohugoio/hugo/releases/latest | grep browser_download_url | grep extended | grep linux-amd64.deb | cut -d '"' -f 4 | xargs curl -L -o hugo.deb
sudo dpkg -i hugo.deb
# 验证安装
hugo version

其他 Linux 发行版可将上述命令中的 linux-amd64.deb 替换为对应包格式（如 Arch 使用 pacman -S hugo，安装后再替换为扩展版二进制）。

1.4 本地 Hugo 项目搭建

确保本地已安装 Hugo 环境（上一步完成），执行以下命令创建并初始化站点：

1
2
3
4


# 新建 Hugo 站点
hugo new site my-hugo-blog
# 进入站点目录
cd my-hugo-blog

安装你喜欢的 Hugo 主题（以 Git 子模块方式安装为例，是主流主题的通用安装方式）：

1
2


# 示例：安装 PaperMod 主题，可替换为其他主题
git submodule add https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod

将主题配置写入站点配置文件 hugo.toml（旧版为 config.toml）：

1
2
3
4


baseURL = "https://example.com/"
languageCode = "zh-cn"
title = "我的个人博客"
theme = "PaperMod"

本地预览站点，确认可正常运行：

1

hugo server

访问 http://localhost:1313 能看到博客页面，即本地项目搭建完成。

1.5 将 Hugo 项目推送到 GitHub 仓库

Cloudflare Pages 通过拉取 GitHub 仓库代码触发自动构建，需先将本地项目同步到 GitHub 远程仓库。

步骤 1：创建 GitHub 空仓库

登录 GitHub 账号，点击右上角「+」→ 选择「New repository」
填写仓库名称（如 my-hugo-blog），可见性选择「Public」或「Private」均可，Cloudflare Pages 免费计划均支持
不要勾选「Add a README file」「Add .gitignore」「Choose a license」初始化选项，避免与本地文件冲突
点击「Create repository」完成创建

步骤 2：配置 .gitignore 排除冗余文件

在项目根目录创建 .gitignore 文件，排除无需提交的构建产物与临时文件：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


# Hugo 构建生成的静态文件
public/
resources/_gen/

# 系统临时文件
.DS_Store
Thumbs.db

# 前端依赖目录（若使用 npm 等工具）
node_modules/

步骤 3：初始化 Git 并推送代码

打开终端，进入 Hugo 项目根目录，依次执行以下命令：

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


# 初始化本地 Git 仓库（未初始化时执行）
git init

# 将所有文件加入暂存区
git add .

# 提交到本地仓库
git commit -m "init: 初始化 Hugo 博客项目"

# 绑定远程仓库地址（替换为你自己的 GitHub 仓库地址）
git remote add origin https://github.com/你的用户名/你的仓库名.git

# 推送到 GitHub main 分支
git branch -M main
git push -u origin main

若主题通过 git submodule 安装，上述命令会自动保留子模块配置，无需额外处理。

二、部署 Hugo 到 Cloudflare Pages

2.1 创建 Pages 项目并连接 GitHub

登录 Cloudflare 控制台，左侧菜单选择 Workers & Pages
点击「Create application」，切换到 Pages 标签页
点击「Connect to Git」，授权 Cloudflare 访问你的 GitHub 账号
选择刚才创建的 Hugo 博客仓库，选择部署分支（默认 main）

2.2 构建设置与环境变量

在构建设置页面，按以下参数配置：

Framework preset（框架预设）：选择 Hugo，系统会自动填充基础构建参数
Build command（构建命令）：
- 普通主题：保持默认 hugo 即可
- 子模块安装的主题：修改为 git submodule update --init --recursive && hugo
Build output directory（构建输出目录）：保持默认 public

必须添加环境变量，否则可能出现版本不兼容、主题编译失败问题：

变量名	变量值	作用
`HUGO_VERSION`	与你本地安装的 Hugo 版本一致（如 `0.143.1`）	固定构建环境的 Hugo 版本，避免版本差异
`HUGO_EXTENDED`	`true`	启用 Hugo 扩展版，支持 SCSS/Sass 编译，绝大多数主流主题必需

配置完成后，点击「Save and Deploy」开始部署。

2.3 验证部署结果

等待 1-3 分钟构建完成，部署成功后会获得一个 xxx.pages.dev 格式的免费域名，点击即可访问你的博客站点。

三、绑定自定义域名

3.1 将域名托管至 Cloudflare（推荐）

将域名的 DNS 解析托管到 Cloudflare，可实现自动证书续期、全量 CDN 加速、一键绑定等最佳体验。

Cloudflare 首页点击「Add Site」，输入你的域名
选择免费套餐（Free Plan），点击继续
Cloudflare 会自动扫描现有 DNS 记录，确认无误后继续
到你的域名注册商后台，将域名的 Nameserver（NS 服务器）修改为 Cloudflare 提供的两组地址
返回 Cloudflare 点击「Done, check nameservers」，等待 NS 生效（通常几分钟到几小时）

3.2 Pages 项目绑定自定义域名

进入你的 Pages 项目，切换到 Custom domains 标签
点击「Set up a custom domain」，输入你要绑定的域名（支持根域名如 example.com 或子域名如 blog.example.com）
若域名已托管到 Cloudflare，系统会自动创建 DNS 解析记录并签发 SSL 证书
等待状态变为 Active，即绑定成功

若域名未托管到 Cloudflare，需手动在域名注册商处添加 CNAME 记录，指向你的 xxx.pages.dev 地址，但无法享受自动续期等优化，不推荐。

3.3 SSL 加密模式配置（必做，避免重定向循环）

新接入的域名默认加密模式可能导致 HTTPS 重定向循环，需手动调整：

进入 Cloudflare 域名控制台，左侧菜单选择 SSL/TLS → 概述
将加密模式设置为完全或 完全（严格）
开启「始终使用 HTTPS」选项，确保全站加密访问

3.4 修改 Hugo 基础配置

更新 Hugo 配置文件 hugo.toml 中的 baseURL 为你的自定义域名：

1

baseURL = "https://你的自定义域名/"

修改后提交并推送到 GitHub，Cloudflare Pages 会自动触发重新构建，站点链接即可全部适配新域名。

四、配置 Cloudflare R2 对象存储（图床）

R2 提供免费存储空间与免费流出流量，搭配 Cloudflare CDN，非常适合作为博客图床存储图片等静态资源。

4.1 创建 R2 存储桶

Cloudflare 左侧菜单选择 R2
点击「Create bucket」创建存储桶
填写存储桶名称（全局唯一，全小写，如 my-blog-images）
位置选择「自动」，存储类选择「标准」
点击「Create bucket」完成创建

4.2 开启公开访问与自定义域名

方式一：r2.dev 免费子域名（仅测试用）

进入存储桶 → 设置 → 公开访问
点击「允许访问」，即可获得 https://pub-xxx.r2.dev 格式的公网地址
注意：该域名在中国大陆地区访问稳定性差，仅建议临时测试使用

方式二：绑定自定义域名（生产推荐）

进入存储桶 → 设置 → 自定义域 → 点击「连接域」
输入图床专用子域名，如 img.example.com（域名需已托管到 Cloudflare）
系统自动配置 DNS 解析与 CDN 加速，生效后即可通过自定义域名访问文件
该方式国内访问稳定性远优于 r2.dev，且享受 CDN 缓存

4.3 获取 R2 API 访问密钥

用于后续通过工具批量上传图片，遵循最小权限原则配置：

Cloudflare 右上角头像 → 「我的个人资料」 → 「API 令牌」
点击「创建令牌」，选择「编辑 Cloudflare R2」模板
权限保持默认，在「账户资源」中可指定仅授权当前存储桶，提升安全性
TTL 选择「永久」，点击「继续以显示摘要」→「创建令牌」
创建成功后，保存好 Access Key ID、Secret Access Key，同时在 R2 概览页复制你的账户 ID

密钥仅显示一次，请妥善保存；泄露后请立即吊销并重新生成。

五、Hugo 中集成 R2 图床

5.1 配置全局 CDN 参数

在 Hugo 配置文件 hugo.toml 中添加 R2 访问地址参数：

1
2


[params]
  cdnURL = "https://img.example.com/"  # 替换为你的 R2 自定义域名

5.2 创建图片专用短代码

在项目根目录新建 layouts/shortcodes/r2img.html 文件，写入以下内容：

1
2
3
4


{{- $src := .Get "src" -}}
{{- $alt := .Get "alt" | default "" -}}
{{- $cdnURL := .Site.Params.cdnURL -}}
<img src="{{ printf "%s%s" $cdnURL $src | safeURL }}" alt="{{ $alt }}" loading="lazy">

该短代码会自动拼接 R2 域名与图片路径，并开启懒加载优化。

5.3 文章中插入 R2 图片

在 Markdown 文章中使用以下语法插入图片：

1

{{< r2img src="posts/hello-world/cover.jpg" alt="文章封面图" >}}

其中 src 为图片在 R2 存储桶中的路径，alt 为图片描述。

5.4 图片上传到 R2 的常用方式

网页端手动上传：进入 R2 存储桶，直接拖拽文件或点击「上传」按钮，适合少量图片
PicGo 批量上传：安装 PicGo 的 S3 插件，配置 R2 的 Endpoint、AK、SK、存储桶名，实现剪贴板 / 拖拽一键上传
命令行批量上传：使用 AWS CLI 或 rclone 工具，适合大量图片迁移

S3 兼容配置通用参数：

Endpoint：https://<你的账户ID>.r2.cloudflarestorage.com
Region：auto
Access Key / Secret Key：上文获取的 API 密钥

六、优化设置与常见问题

6.1 免费额度汇总

服务	免费额度说明
Cloudflare Pages	无限站点、无限流量；账户共享每月 500 次构建次数，单次构建最长 20 分钟
Cloudflare R2	10GB 标准存储；每月 100 万次 Class B 读取操作、10 万次 Class A 写入操作；流出流量完全免费
SSL 证书	免费通用证书，自动续期，无数量限制

6.2 常见问题排查

构建失败

检查 HUGO_VERSION 是否与本地一致，是否添加了 HUGO_EXTENDED=true
主题为子模块安装的，确认构建命令包含 git submodule update --init --recursive
在 Pages 项目的「Deployments」中点击失败记录，查看详细构建日志定位问题

网站出现重定向循环

检查 SSL/TLS 加密模式是否设置为「完全」或「完全（严格）」，禁止使用「灵活」模式

R2 图片无法访问

确认已开启公开访问或绑定自定义域名
检查图片路径是否正确，域名是否生效
国内访问请务必使用自定义域名，避免 r2.dev 域名的网络问题