Pagefind 做了什么#

Pagefind 会扫描构建后的页面，把正文内容拆成索引文件。它关注的是最终 HTML，不是 Markdown 源文件。所以只修改 src/content/posts 但没有重新 build，搜索结果不会变化。

如果构建日志里显示索引页面数量明显少于文章数量，就要检查是否有页面没有生成，或者某些页面被排除。

我会检查的文件#

1
ls -lh dist/pagefind/pagefind.js
2
find dist/pagefind -type f | wc -l
3
ls -lh dist/api/allPostMeta.json

pagefind.js 能访问说明前端搜索脚本存在；allPostMeta.json 更新说明文章元数据已经进入构建产物。这两个都正常，再去看搜索框的结果才有意义。

常见问题#

• 新文章页面是 200，但搜索不到：大概率没有重新构建 Pagefind。

• 本地能搜，线上搜不到：可能上传了 Markdown，却没有替换线上 dist。

• 搜索结果标题乱码：先检查 Markdown 文件编码是不是 UTF-8。

• 搜索结果太少：检查文章是否 draft，或构建日志里 Pagefind 扫描了多少页面。

发布后的验证#

发布后我会直接访问 /pagefind/pagefind.js，再打开 /api/allPostMeta.json 看文章总数。最后用新文章标题里的关键词搜索一次，例如 rolling、YOLO、Nginx。

实战复盘#

复盘《Pagefind 搜索索引更新笔记》时，我会把它当成一个站点维护动作，而不是单篇文章。凡是影响首页、分类、RSS、Sitemap、搜索索引或旧链接的改动，都要在发布后做一次线上验证。

如果只在源码里看起来正确，但线上接口或页面没有变化，就说明构建或发布链路还有问题。博客维护类内容必须把“怎么确认已经生效”写清楚。

以后继续扩展这类文章时，可以补充真实命令输出、截图前后的差异，以及回滚路径。这样文章会更接近操作手册，而不是零散备忘。

最小验收样例#

验收《Pagefind 搜索索引更新笔记》时，我会选一篇真实文章或一个真实页面作为样例，而不是只看源码。先确认页面能打开，再确认列表、分类、归档、搜索这些入口都能找到它。

如果文章讲的是站点维护，还要记录修改前后差异：改了哪个文件、构建产物是否更新、线上 HTTP 状态码是多少。这样后面出问题时，可以直接回到这次验收记录。

小结#

搜索问题不要只盯搜索框。先确认 Markdown 进入构建，再确认 HTML 被 Pagefind 扫描，最后才检查前端交互。