先给判断

Pagefind 的关键不是在页面上放一个搜索框，而是把“什么内容进入索引”变成构建契约。官方文档说明，Pagefind 在静态站点生成器完成后运行，把索引写入生成目录；多语言模式根据 html 的 lang 属性为不同语言建立和加载索引。双语站点若先解决了 UI、却没有解决语言、草稿和构建顺序，搜索结果仍然会错。

构建后的索引

Pagefind 不需要你手写一个数据库。站点先输出 HTML，再由 Pagefind 扫描输出目录生成静态 search bundle。它没有常驻服务器，浏览器加载的是构建时生成的索引文件。因此 dev server 上看不到最终搜索行为并不奇怪；要验证结果，必须对真实 production 或 preview build 运行索引。

这也意味着草稿隔离要发生在索引之前。生产构建如果把 draft: true 页面写进输出目录，Pagefind 很可能会把它当作普通页面。正确的门是：先用 production build 排除草稿，再生成 Pagefind，再检查索引中没有草稿 route。

双语边界

官方多语言文档说明，Pagefind 会读取 HTML 的 lang，分别索引并在浏览器选择相同语言的索引；英文支持词干化，中文等专门语言使用分词但不使用相同的 stemming 机制。中文搜索不能简单套用英文的词根规则，英文也不应因为页面混入中文 metadata 就改变词面过滤。

最小检查：

zh 页面
  lang = zh-CN
  只查中文索引
en 页面
  lang = en
  只查英文索引
production build
  排除 draft
Pagefind
  只扫描 production 输出

相关性不是索引数量

Pagefind 的召回器可以给出候选，应用层仍要检查结果是否满足用户词面。尤其英文词干化可能让低置信度候选进入结果；如果产品要求“完全无关的普通词必须为零”，就要从 Pagefind 的 data()、正文和 locations 做通用词面校验，而不是写三个异常词黑名单或依赖绝对 score 阈值。

每个结果的 data() 最好只加载一次，过滤与渲染共用同一份数据；异步查询要带 request generation，旧 Promise 不能覆盖新查询。中文路径则保持自己的分词和语言索引规则。

常见失败

把 Pagefind 当作运行时数据库；在 dev server 上判断 production 搜索；忘记设置 lang；把 draft 页面留在输出目录；用高亮 HTML 推断原始匹配；为了过测试删除草稿门；以及只看结果数量而不看链接和摘要，都是常见误区。

可复现验收

npm run build:production
npm run test:search
检查索引语言
检查公开 route
查询中文、英文正例
查询随机缺失词
快速输入：最后一次查询赢得渲染

来源与边界

Pagefind 官方文档和仓库支持构建后索引、lang 多语言模式及中文分词说明。本文的草稿隔离、应用层精度门和 Omnihex 结果检查是本站实现的工程方法，不是 Pagefind 对搜索质量的保证。