使用 Hugo + Stack Starter 搭建博客并部署到 Cloudflare Pages

本文记录如何用官方推荐的 Hugo Theme Stack Starter 快速搭好个人博客，并把站点部署到 Cloudflare Pages。Stack 是 Jimmy Cai 维护的一套现代、偏阅读体验的 Hugo 主题；Starter 仓库已经接好 Hugo Modules，省去手动装子模块的麻烦。

前置条件

Git：用于拉代码与连接 Pages。
Hugo Extended：Stack 依赖 SCSS 等资源处理，请安装带 Extended 的版本（与 Hugo 官方安装说明一致）。
Go：Hugo Modules 会用到本机 Go 环境（一般装 Hugo 时文档会一并说明）。

终端里执行 hugo version，输出中应包含 extended 字样。

第一步：使用 Stack Starter 初始化项目

打开终端，执行以下命令克隆脚手架，并切断与原模板的 Git 历史联系：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
# 1. 克隆脚手架代码 (重命名为你的博客目录，例如 my-blog)
git clone https://github.com/CaiJimmy/hugo-theme-stack-starter.git my-blog

# 2. 进入目录
cd my-blog

# 3. 删除原有的 git 历史，准备作为你自己的私有仓库
rm -rf .git  # Windows 下用 rd /s /q .git
git init

# 4. 初始化 Go Module (这一步会自动拉取 Stack 主题的最新依赖)
go mod tidy

根目录的 go.mod 会锁定主题模块版本；若主题有更新，可在项目根执行：

1
2
hugo mod get -u
hugo mod tidy

第二步：本地运行与预览

在项目根目录执行：

1
hugo server -D

-D 会包含草稿（draft: true 的文章）。
浏览器打开终端提示的地址（一般为 http://localhost:1313）。

停止服务用 Ctrl+C。

正式构建静态文件：

1
hugo --minify

生成结果在 public/ 目录，部署时 Cloudflare 也是指向这一目录。

第三步：按需修改站点配置

主要关注 config/_default/ 下的文件。

`config.toml`

baseurl：部署前改成你的站点地址，例如 https://你的子域.pages.dev/ 或自定义域名（末尾建议保留 /）。
title：站点标题。
languageCode / defaultContentLanguage：语言；中文常用 zh 或 zh-cn，并与主题 i18n 文件名对应。
hasCJKLanguage = true：内容以中日韩文为主时建议开启，摘要与字数统计更准确。
timeZone：例如 Asia/Shanghai。
disqusShortname：若不用 Disqus 评论，可留空或按主题文档关闭。

`params.toml`

mainSections：参与首页、归档的文章类型，一般为 ["post"]。
[sidebar]：头像路径、副标题、emoji 等。
[article]：阅读时间、数学公式、许可证文案等。

写文章

文章放在 content/post/ 下，可用 Page Bundle（每篇一个文件夹 + index.md），便于同目录放图片。Front matter 至少包含 title、date；draft: true 表示草稿，上线前改为 false 或发布时用 hugo 不带 -D。

第四步：部署到 Cloudflare Pages

思路是：把仓库推到 GitHub（或 GitLab），在 Cloudflare Dashboard 里新建 Pages 项目并绑定该仓库，由云端执行 hugo 生成 public/。

4.1 准备仓库

1
2
3
4
git add .
git commit -m "Initial blog setup"
git remote add origin <你的仓库 HTTPS 或 SSH 地址>
git push -u origin main

分支名可能是 main 或 master，与 Pages 里选择的分支一致即可。

4.2 在 Cloudflare 创建 Pages 项目

登录 Cloudflare Dashboard，进入Build → Compute → Workers & Pages → Create application → Connect Github → Looking to deploy Pages? Get started。
授权并选中你的博客仓库。
配置构建：

项	建议值
Framework preset	Hugo
Build command	`hugo --minify`
Build output directory	`public`
Root directory	`/`（项目在仓库根目录时）

4.3 环境变量（使用 Stack v4 时建议视为必需）

Cloudflare Pages 若未设置 HUGO_VERSION，构建环境可能仍使用较旧的 Hugo（日志里常见 v0.147.x）。而 Hugo Theme Stack v4（如 Starter 默认锁定的 v4.0.0-beta.15）在 go.mod / 模块元数据里会要求 最低 Hugo 0.157.0 且为 Extended；版本过低时会出现：

警告：Module "…/hugo-theme-stack/v4" is not compatible with this Hugo version: Min 0.157.0 extended
报错：can't evaluate field IsImageResourceWithMeta in type interface {}（主题模板用到了新版本资源 API，旧 Hugo 没有该字段）

在 Pages 项目的 Settings → Environment variables 中，为 Production 与 Preview（若需要）各添加：

变量名	示例值	说明
`HUGO_VERSION`	`0.159.0`	填 ≥ 0.157.0 的 Release 版本号；与本机 `hugo version` 对齐最省事。

保存后 重新触发一次部署（Retry deployment 或推一个空 commit）。Cloudflare 拉取的会是带 extended 的对应版本，一般无需再单独指定 Extended 变量。

4.4 发布与域名

首次构建成功后，会得到 *.pages.dev 子域。若使用自定义域名，在 Pages 项目里 Custom domains 按向导把 DNS 指到 Cloudflare 即可。

重要：将 config/_default/config.toml 里的 baseurl 改成最终访问地址（含 https:// 与尾部 /），否则站内链接、RSS、OG 等可能指向错误域名。改完后重新推送触发构建。

常见问题简述

IsImageResourceWithMeta / 主题不兼容当前 Hugo：几乎都是云端 Hugo 低于主题要求。在 Cloudflare Pages 设置 HUGO_VERSION 为 ≥ 0.157.0（如 0.159.0）后重试构建即可。
hugo: command not found：本机未安装或未加入 PATH；Pages 侧则检查是否选了 Hugo 预设或构建镜像是否含 Hugo。
主题或模块拉取失败：本机执行 hugo mod get、hugo mod tidy；CI 需能访问 GitHub（一般无问题）。
样式异常：确认使用 Hugo Extended，而不是纯社区版。

以上即从 Stack Starter 起步到 Cloudflare Pages 上线的一条完整路径。之后只需专注写 Markdown、提交 Git，Pages 会自动构建发布。