# 常见问题排查
URL: https://caijiao.org/pagefind/tutorial-09-troubleshooting
Source: docs/pagefind/tutorial-09-troubleshooting.md
Description: 汇总 Pagefind 无搜索结果、索引为空、中文搜索不准、路径错误、部署后资源 404、结果混入导航等问题的排查方法。
Pagefind 的问题通常集中在构建顺序、索引范围、资源路径和语言配置。排查时先确认索引是否生成，再看浏览器能否加载资源。
## 没有任何搜索结果
先检查构建日志中是否出现类似信息：
```text
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`。
## 结果里混入导航和页脚
优先给正文区域加：
```html
...
```
如果模板里有重复推荐、上一篇下一篇、版权信息等内容，可以局部添加：
```html
...
```
## 中文搜索效果差
检查三点：
1. 页面是否有正确的 ``。
2. 是否使用了扩展版本，或通过 npm 包运行 Pagefind。
3. 单语言中文站是否适合添加 `--force-language zh`。
技术词汇较多的站点，可以把英文名、中文别名、缩写写进标题、首段或元数据中，帮助用户用不同关键词命中同一页面。
## 摘要显示了 HTML
Pagefind 的 `excerpt` 用于展示带高亮的摘要，通常会包含 ``。如果你的界面只想展示纯文本，使用 `plain_excerpt`。
如果渲染自定义字段或元数据，仍应根据前端框架规则进行转义，避免把未处理文本直接作为 HTML 插入。
## 构建速度变慢
内容站页面很多时，Pagefind 需要扫描全部 HTML。可以考虑：
- 只把需要搜索的内容输出到索引范围中。
- 用 `--glob` 排除不需要索引的 HTML。
- 避免把大型代码示例、日志或生成数据全部放进正文索引。
- 在 CI 中缓存依赖，但不要缓存旧索引覆盖新内容。
Pagefind 索引应由当前构建产物重新生成，这样搜索结果才会和线上页面保持一致。