Hugo博客搭建复盘
@Jiayi
前言：这次不是“搭个壳子就结束”
这篇是我给自己做的一次阶段复盘。
一开始我只是想先把 Hugo 跑起来，结果一路做下来，已经不只是“写两篇文章”这么简单，而是把一个能本地写作、能线上发布、还能持续维护的博客雏形真正搭起来了。
我们做出了什么？
先说结果：这个博客已经具备“能用 + 能看 + 能更新”的基础能力。
- 不装主题，先手写最小首页，解决
Page Not Found - 文章页可访问，Markdown 渲染正常
- 归档页可用，按年分组、按月统计、按时间倒序
- 标签页、分类页可用，导航高亮正常
- TOC 可用（桌面端固定、移动端折叠）
- 目录支持平滑滚动与当前章节高亮（scroll spy）
- 自定义 shortcodes 可用（时间线、踩坑提醒）
- 表格样式优化，窄屏支持横向滚动
- 移动端兼容修复（长内容不再挤出屏幕）
关键节点
- 阶段 1本地访问先遇到 404，先做最小首页兜底。
- 阶段 2文章、归档、标签、分类全部打通。
- 阶段 3主题迁移后，之前做的一些交互和样式丢失。
- 阶段 4通过 Hugo 覆盖机制，逐步把关键设计加回。
- 阶段 5Cloudflare Pages 免费部署成功。
主题迁移：模板很香，但“丢功能”很真实
后面我们选了 neopost。
页面确实更好看了，但很快发现：我之前自己做的很多细节不见了，比如 TOC 交互、时间线短代码、提醒块样式等。
这次最大的收获是：Hugo 不是二选一，不是“用了主题就不能保留自定义”。
正确姿势是：
- 保留主题整体外观
- 在项目层通过
layouts/和static/覆盖主题文件 - 只恢复关键功能，避免一次改太多
一句话：主题是起点，不是终点。
免费上线 Cloudflare：踩坑后就很顺
上线时我先误入 Workers 链路，导致构建失败；切到 Pages 项目后就顺利了。
现在流程非常清晰：
- 本地改内容/样式
git add+git commit+git push- Cloudflare Pages 自动构建并发布
踩坑提醒
Cloudflare 有 Workers 和 Pages 两条路。Hugo 静态博客优先 Pages。
如果日志里出现
如果日志里出现
npx wrangler deploy，大概率走错链路了。如果重来一次，我会这样做
- 先定主题（先稳定大框架）
- 再逐步加功能（TOC、shortcode、归档、样式）
- 每做一批就上线预览，不堆到最后一次性排错
这就是最朴素的工程习惯：小步提交，持续验证。
收尾
现在这个博客虽然还不是终极形态，但已经是一个可持续维护的版本。
后面我会继续写内容，也会慢慢打磨视觉和写作 workflow。
如果你也在从 0 搭 Hugo，希望这篇能给你一点信心：先跑起来，再变漂亮，最后再变强大。
补充：搭建 Hugo 博客需要哪些技术栈？
如果把这次实践拆开看，核心技术栈可以分成 6 层：
- 内容层：Markdown + Front Matter（title/date/tags/categories/draft）
- 配置层：
hugo.toml（菜单、分页、TOC、baseURL） - 模板层：Hugo Layouts / Partial / Theme Override（
layouts/覆盖主题） - 样式交互层：CSS + 少量 JavaScript（目录高亮、平滑滚动、响应式修复）
- 工程协作层：Git（分支、提交、回滚、同步）
- 部署层：Cloudflare Pages（Git push 后自动构建发布）
这些层不是“必须一次学完”，而是可以边做边补。
补充：我的 Hugo 学习路线图
我现在更推荐下面这条路线（先可用，再美化，再工程化）：
graph TD
A["Markdown 与 Front Matter"] --> B["Hugo 基础命令与目录结构"]
B --> C["hugo.toml 配置：菜单/分页/TOC"]
C --> D["主题使用与覆盖机制：layouts/static"]
D --> E["Shortcode 与样式优化：CSS/JS"]
E --> F["Git 工作流：分支/提交/回滚"]
F --> G["Cloudflare Pages 自动部署"]
G --> H["持续迭代：性能/SEO/写作体系"]
一句话总结：先跑通发布链路，再打磨体验，最后再谈自动化。