上线前备忘录:静态站从零到 Cloudflare Pages
目录
这套流程从零跑到 Cloudflare Pages,踩了不少坑。浓缩成清单,照着做就不会卡。
为什么选静态站、砍掉了哪些后台能力,看 为什么没用带后台的导航程序;为什么最终没做热榜,看 为什么放弃了热榜模块。逐条决策的 A/B/C 对比与死因,见仓库内
docs/10-决策记录.md(本站文档,非公开页面)。
阶段 0:装 Hugo
- 包管理器(scoop/choco/winget)全都没有,走 GitHub Releases 手动装
- 装 extended 版(将来 Sass 编译要用),不是标准版
- 下载 21.5 MB 实测花了 19 分钟,GitHub 有时极慢,要有耐心
- 版本判定:v0.170.0 起
hugo version不再打印+extended。别误判。改用hugo env看libsass/sass,或直接看二进制里有没有libsass字符串
阶段 1:配置真值
hugo.toml 三个关键值,最后绑定的域名一定要写对:
baseURL = "https://daomind.dpdns.org/" # 末尾 / 不能丢,影响 canonical/sitemap/RSS
title = "DaoMind"
[params]
author = "DaoMind"
阶段 2:本地双验证
hugo --gc --minify # 生产构建,检查 public/ 产物齐全
hugo server -D # 开发服务器,逐个路由确认 200
- 检查
public/:index.html、sitemap.xml、index.xml、robots.txt、404.html - 检查 canonical 是否已是最终域名
- 有 3 个弃用警告(
languageCode→locale、.Site.LanguageCode→.Site.Language.Locale、.Site.Data→hugo.Data),本次不修,等 Hugo 真删了再迁
阶段 3:首次提交
- 仓库级配置身份(不要动全局):
git config user.name/user.email .gitignore必须含public/、resources/、.hugo_build.lock——提交前用git check-ignore确认生效- 提交后验证
git statusclean、public/不在跟踪列表
阶段 4:推送
SSH 大概率不通(实测:Permission denied (publickey),因为 ssh-agent 没跑 + key 名非默认)。直接走 HTTPS:
git remote add origin https://github.com/DaoMind/DaoMind.git
git push -u origin main
浏览器授权即可,不需要 SSH key。
阶段 5:Cloudflare Pages
- 构建镜像默认 Hugo
0.147.7,但支持任意版本,用环境变量HUGO_VERSION指定 - Production 和 Preview 两处都要填
- 如果
HUGO_VERSION=0.170.0构建失败(刚发布 3 天,镜像可能滞后),降到 0.167.0,并本地重装成 0.167.0,保持「本地=云端」
阶段 6:域名
daomind.dpdns.org是 DNSPod 免费二级域名的子域,根域不可控、改不了 NS- 走 External DNS:Cloudflare Pages 给一个 CNAME 目标,DNSPod 侧加
CNAME指向它 - 风险:DNSPod 免费套餐可能不允许指向外部的 CNAME。如果卡住,降级用
xxx.pages.dev先上
三条铁律
- 零依赖:不碰 npm、不引 CDN、不用主题
- Git 即全部资产:内容、配置、文档全是纯文本,
public/是构建产物,不入库 - 本地 = 云端:本地和 Pages 的 Hugo 版本必须一致,否则「我本地跑得通」就是假象