# Pagefind 教程

URL: https://caijiao.org/pagefind/
Source: docs/pagefind/index.md
Description: Pagefind 是一个面向静态网站的本地全文搜索工具。本教程讲解安装、构建后索引、搜索 UI、JavaScript API、索引范围、元数据、筛选、中文搜索和 SSG 集成实践。

Pagefind 是一个为静态网站生成全文搜索索引的工具。它通常在站点构建完成后运行，读取输出目录中的 HTML 文件，并把搜索所需的静态资源写入站点目录。

![Pagefind Logo](/images/pagefind/b3bd25ab-c820-4df0-90ad-d93b2df7a3af.webp)

与依赖服务端搜索接口的方案不同，Pagefind 的查询在浏览器中完成，适合文档站、博客、产品手册、课程站点和静态生成的内容网站。

## 适合什么场景

| 场景 | 说明 |
| --- | --- |
| 静态文档站 | 构建后扫描 HTML，部署时只需要托管静态文件 |
| 博客与教程站 | 支持按正文、标题、元数据搜索 |
| 多语言站点 | 可按页面 `lang` 识别语言，也可强制生成单一语言索引 |
| 自定义搜索框 | 可用官方组件，也可用 JavaScript API 接入现有 UI |

## 学习路线

1. 阅读 [Pagefind 是什么](/pagefind/tutorial-01-introduction)，理解它和传统搜索服务的区别。
2. 通过 [安装与运行](/pagefind/tutorial-02-installation) 在构建后的站点上生成索引。
3. 学习 [索引范围控制](/pagefind/tutorial-03-indexing) 和 [中文搜索配置](/pagefind/tutorial-07-chinese-search)，避免把导航、页脚或无关内容纳入结果。
4. 根据项目需要选择 [官方搜索 UI](/pagefind/tutorial-04-search-ui) 或 [JavaScript API](/pagefind/tutorial-05-search-api)。
5. 用 [元数据与筛选](/pagefind/tutorial-06-metadata-filters) 丰富搜索结果和分类过滤。
6. 最后参考 [SSG 集成实践](/pagefind/tutorial-08-ssg-integration) 与 [常见问题排查](/pagefind/tutorial-09-troubleshooting) 上线。

## 参考资料

- [Pagefind 官方文档](https://pagefind.app/docs/)
- [Pagefind 索引配置](https://pagefind.app/docs/indexing/)
- [Pagefind 搜索 API](https://pagefind.app/docs/api/)
- [Pagefind 多语言搜索](https://pagefind.app/docs/multilingual/)