这套流程从零跑到 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 status clean、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 先上

三条铁律

  1. 零依赖:不碰 npm、不引 CDN、不用主题
  2. Git 即全部资产:内容、配置、文档全是纯文本,public/ 是构建产物,不入库
  3. 本地 = 云端:本地和 Pages 的 Hugo 版本必须一致,否则「我本地跑得通」就是假象