评论、搜索与联系表单集成

原 WordPress 主题的评论、搜索、联系表单在 Hugo 中由第三方服务替代，全部通过 config.toml 开关控制，未启用时页面不含任何相关脚本（性能优先）。

功能	方案	默认
评论	Giscus / Utterances	关闭
搜索	Pagefind	开启
联系表单	Formspree / Netlify Forms	关闭

评论：Giscus（推荐）

一次性准备（GitHub 侧）

仓库设为公开；
Settings → General → Features → 开启 Discussions；
安装 giscus App：https://github.com/apps/giscus → Configure → 选择该仓库。

生成配置

打开 https://giscus.app/zh-CN，选择仓库与分类，复制生成的配置填入：

1[params.comments]
2  provider   = "giscus"
3  repo       = "你的用户名/你的仓库"
4  repoId     = "R_kgDOxxxxxxx"
5  category   = "Announcements"
6  categoryId = "DIC_kwDOxxxxxxx"
7  theme      = "light"     # 或 dark；勿用 preferred_color_scheme（SSR 缺陷）

排查：页面报 “giscus is not installed” → App 未安装/仓库非公开/Discussions 未开启；控制台 MIME 报错 → theme 用了非法值。

Utterances 替代

只需 repo 与 theme（github-light / github-dark）两个字段，其余照抄 utteranc.es 即可。

搜索：Pagefind（本站已启用）

完整管线

1npm install                 # 首次：安装 pagefind
2hugo --minify               # 构建站点
3npx pagefind --site public  # 生成 /pagefind/ 索引

配置与使用

1[params.search]
2  provider    = "pagefind"
3  placeholder = "搜索…"

页眉放大镜展开输入框，提交后跳转 /search/?q=关键词，Pagefind UI 自动读取 q 参数；
中文自动识别（索引日志显示语言与页面数）；结果链接为站内相对路径，本地/线上一致；
搜索页自身通过 data-pagefind-ignore 排除出索引；单篇想排除可给该页加同属性；
本地预览：npx pagefind --serve（hugo server 不生成索引）；
baseURL 必须与部署域名一致，否则结果链接指向错误地址。

联系表单：Formspree

在 https://formspree.io 注册并创建表单，得到 https://formspree.io/f/xxxx 端点；
配置：

1[params.contactForm]
2  provider = "formspree"
3  endpoint = "https://formspree.io/f/你的表单ID"

在联系页插入短代码（本演示的联系页即示例）：

1


姓名: 联系表单未启用。请在 config.toml 中设置 params.contactForm.provider 与 endpoint（详见 README）。

表单已内置 honeypot 防垃圾字段（_gotcha），样式与主题输入框一致；
Netlify Forms 用户：provider = "netlify"（无需 endpoint，表单自动收集提交）。

通用原则

三个服务一致的设计：provider = "none" 时零脚本加载；配置即用、关闭即无痕。评论与表单默认关闭是为了开箱即用不被第三方依赖拖累，需要时按本文配置即可。