常见问题排查

Pagefind 的问题通常集中在构建顺序、索引范围、资源路径和语言配置。排查时先确认索引是否生成，再看浏览器能否加载资源。

没有任何搜索结果

先检查构建日志中是否出现类似信息：

Indexed 120 pages
Indexed 8400 words

如果页面数是 0，常见原因包括：

• --site 指向了错误目录。
• Pagefind 在 HTML 生成前运行。
• 站点使用了 data-pagefind-body，但需要搜索的页面没有该属性。
• --glob 或 --root-selector 配置过窄。

浏览器报 404

如果控制台提示 /_pagefind/pagefind.js 404：

• 确认构建产物中存在 _pagefind/pagefind.js。
• 确认部署平台发布的是运行 Pagefind 之后的目录。
• 如果站点部署在子路径下，需要调整导入路径或设置浏览器端 bundlePath。

结果里混入导航和页脚

优先给正文区域加：

<main data-pagefind-body>
  ...
</main>

如果模板里有重复推荐、上一篇下一篇、版权信息等内容，可以局部添加：

<div data-pagefind-ignore>
  ...
</div>

中文搜索效果差

检查三点：

1. 页面是否有正确的 <html lang="zh-CN">。
2. 是否使用了扩展版本，或通过 npm 包运行 Pagefind。
3. 单语言中文站是否适合添加 --force-language zh。

技术词汇较多的站点，可以把英文名、中文别名、缩写写进标题、首段或元数据中，帮助用户用不同关键词命中同一页面。

摘要显示了 HTML

Pagefind 的 excerpt 用于展示带高亮的摘要，通常会包含 <mark>。如果你的界面只想展示纯文本，使用 plain_excerpt。

如果渲染自定义字段或元数据，仍应根据前端框架规则进行转义，避免把未处理文本直接作为 HTML 插入。

构建速度变慢

内容站页面很多时，Pagefind 需要扫描全部 HTML。可以考虑：

• 只把需要搜索的内容输出到索引范围中。
• 用 --glob 排除不需要索引的 HTML。
• 避免把大型代码示例、日志或生成数据全部放进正文索引。
• 在 CI 中缓存依赖，但不要缓存旧索引覆盖新内容。

Pagefind 索引应由当前构建产物重新生成，这样搜索结果才会和线上页面保持一致。