Hugo

本文记录这个博客的搭建方式，从买域名到发布一个静态站点。技术选型和步骤与本站的实现保持一致。 这套技术栈长什么样 一句话概览：用 Hugo 把 Markdown 编译成静态页面，源码在 GitHub，Cloudflare Pages 连接 GitHub 仓库并在 Cloudflare 侧构建、托管，域名解析和 CDN 也在 Cloudflare。 各部分的分工： 组件 作用 Hugo 静态站点生成器，把 content/ 下的 Markdown 编译成 HTML GitHub 存放源码，作为部署的触发源 Cloudflare Pages 连接 GitHub 仓库，执行 hugo --minify 构建并托管产物 Cloudflare DNS 域名解析，把自定义域名指向 Pages 项目 Cloudflare CDN 边缘缓存与加速，Pages 默认自带 整个流程没有用 GitHub Actions，也没有容器化构建，构建这一步完全由 Cloudflare Pages 在它自己的环境里完成。基础站点的构建命令就是一句 hugo --minify；本站为了顺带生成搜索索引，把它包成了一个很短的脚本（见下文进阶模块），思路一样。 基础模块 这一部分从 0 到「能访问」。 买域名 域名可以在任意注册商购买，我最早是在 GoDaddy 买的。以 GoDaddy 为例： 打开 godaddy.com，在搜索框里输入想要的域名，看是否可注册。 选一个后缀（.com、.dev 等），加入购物车，结账。注意第一年常有促销价，续费价通常更高，下单前看清续费价格。 结账时可关掉 GoDaddy 自家的一堆增值服务（邮箱、隐私保护等），后面把 DNS 切到 Cloudflare 后这些大多用不上。 Cloudflare 自己也能直接注册域名（Cloudflare Registrar，按批发价、免费 WHOIS 隐私保护），但支持的后缀有限。如果想要的后缀在它的列表里，直接在 Cloudflare 买、省去后面改 Nameserver 的步骤也可以；后缀不在列表里就按上面的思路在别的注册商买，再把 DNS 切过来。 ...

本文是一条故障记录。 最近两天 wiloon.com 看起来像是“停更”，停在6月28号。但其实 blog 仓库是有更新的，也提交了，只是没能发布出来——博客有大约两天卡在一次构建失败上，而我自己一直不知道。 不是停更，是没发布出去 现象很简单：本地写好、git push 之后，wiloon.com 上看不到新内容。一开始我以为是 CDN 缓存或者部署延迟，没太在意。后来才发现是构建一直在失败——新提交根本没被发布出去。 怎么坏的 原因是文章标题里的一个冒号。 博客用 Hugo，文章开头的 front matter 是一段 YAML。我有几篇 Java/Spring 的文章标题是英中混写的，里面带了「冒号 + 空格」，比如： # breaks the build: ": " makes YAML parse it as a mapping title: Spring WebFlux: 响应式 Web 框架 在 YAML 里，: （冒号加空格）是 key/value 的分隔符。没加引号时，解析器会把这一行当成一个嵌套映射来读，于是报错、Hugo 构建中止。一篇的 front matter 解析失败，整站就一个页面都不生成。 修复其实只要把整个标题值用引号包起来： # fixed: quote the whole value so the colon is just text title: "Spring WebFlux: 响应式 Web 框架" 加上引号之后，构建立刻就恢复了。 ...

说明 这是 wiloon.com 上的测试页面，用于验证「博客文章 → 小红书」推送流程。线上地址：https://wiloon.com/xhs-push-test/。 推送脚本或人工联调时，可用本页校验： 能否正确抓取标题与 description 正文 Markdown 转笔记文案是否正常 部署后 URL 是否可公网访问 固定测试元数据 字段 值 站点 wiloon.com 路径 /xhs-push-test 创建日期 2026-06-24 用途 小红书推送联调 正文摘录（用于 diff） 下面这段文案故意写死，方便对比抓取结果是否与源站一致： 后端工程师的日常笔记站。技术栈：Java、Go、Kubernetes、Ansible。本段为 XHS 推送测试专用固定文本，请勿当作正式内容发布。 可选检查项 标题含英文：XHS Push Test 分类：development 标签：hugo 联调通过后，可删除本页或改为 draft: true 避免出现在站点列表中。

背景 本站使用 Hugo + PaperMod，通过 Containerfile 构建为 Nginx 静态站点镜像。文章约 2800+ 篇（Pagefind 实测索引 2779 页）。本文记录站内搜索方案调研与当前 Pagefind 接入方式。 PaperMod 内置搜索（Fuse.js，已弃用） PaperMod 主题自带基于 Fuse.js 的客户端搜索：Hugo 构建时生成 index.json，搜索页在浏览器里加载全文索引并做模糊匹配。零后端依赖，但本站实测 index.json 约 13MB，需一次下载全部正文，首访慢，中文分词也一般。现已移除 Fuse 相关配置，改用 Pagefind。 Hugo 静态站搜索方案对比 方案 原理 适合规模 优点 缺点 PaperMod Fuse.js 浏览器加载完整 JSON 小站（约 500 篇以内） 零配置、纯静态 大站索引体积大、首访慢；中文分词弱 Pagefind 构建时生成索引，搜索时按查询加载分片 中大型站 首访不必下完全部正文；extended 支持 CJK 需加构建步骤；索引目录总体积未必更小 Lunr.js 类似 Fuse，浏览器建倒排索引 小中型 多主题支持 与 Fuse 同类局限 Algolia DocSearch 构建时推送到 Algolia 云端 文档站 / 开源项目 搜索体验好 需申请、依赖第三方 Meilisearch / Typesense 自托管搜索引擎 大型站 功能强 需跑服务，个人博客偏重 本站实现：Pagefind 采用 Pagefind extended（v1.5.2，支持中文分词）。搜索 UI 使用 Default UI（pagefind-ui.js / PagefindUI），不是 1.5 新推荐的 Component UI。 ...

Giscus 是一个基于 GitHub Discussions 的评论系统，评论数据完全存储在 GitHub，无需额外的数据库或第三方平台。适合托管在 GitHub Pages、Cloudflare Pages 等静态站点。 工作原理 Giscus 把每篇页面的评论映射到 GitHub Discussions 中的一个 Discussion，通过在页面嵌入 <script> 标签加载评论组件。 页面与 Discussion 的映射方式： 映射方式 说明 pathname（推荐） 按页面 URL 路径匹配，最通用 title 按文章标题匹配 og:title 按 Open Graph 标题匹配 前置条件 GitHub 仓库需开启 Discussions 功能：仓库 Settings → Features → Discussions ✓ 安装 Giscus GitHub App：github.com/apps/giscus → Install → 选择目标仓库 获取配置参数 访问 giscus.app，填写仓库名和配置选项，页面底部会生成完整的 <script> 标签，从中获取： data-repo-id（格式 R_kgDO...）：仓库 Node ID data-category-id（格式 DIC_kwDO...）：Discussion 分类 ID Discussion 分类推荐选 Announcements：只有维护者能在 GitHub 网页直接新建 Discussion，普通用户只能通过 Giscus 组件留言，防止垃圾内容。 ...

背景 Hugo 博客（PaperMod 主题）默认没有访问统计。为了了解谁在访问、访问了哪些页面，选择同时接入两套统计： Umami：隐私友好，无 cookie，数据存储在 Umami 服务器 Cloudflare Web Analytics：与 Cloudflare 基础设施集成，数据存储在 Cloudflare 两者不冲突，可以同时运行，便于对比数据。 Umami 特点 无 cookie，无跨站追踪，不需要 GDPR 同意弹窗 免费 Hobby 计划：100K 事件/月，3 个站点，6 个月数据保留 地理位置精度：国家级别 统计维度 页面浏览量（PV）、独立访客数（UV） 每次会话浏览页数、跳出率、平均停留时间 引荐来源、UTM 参数 国家/地区、操作系统、浏览器、设备类型 各页面访问量排行 Browsers：Chrome、Chrome (iOS) 与 iOS Umami 在 Environment → Browsers 里根据访问请求的 User-Agent（UA） 解析浏览器名称，与 Environment → OS 里的操作系统是两套维度，不要混看。 显示名称 含义 Chrome 桌面端或 Android 等环境下的 Chrome；UA 不含 iOS 专用标记 Chrome (iOS) iPhone / iPad 上用 Chrome App 打开；UA 含 CriOS/版本号 iOS 能判断是 iOS 上的浏览器或 WebView，但 未识别 为 Safari、Chrome、Firefox、Edge 等时的兜底分类 列表里 Chrome (iOS) 与 iOS 各计 1 个访客，通常表示 两次不同访问（不同人或不同设备 / 浏览器），不是同一次访问被记了两遍。 ...