🔍 Pagefind 搜索插件使用说明

本文档详细介绍纸鸢博客中 Pagefind 搜索插件的安装、配置和使用方法。

🚀 简介

Pagefind 是一个专为静态网站设计的搜索解决方案，它具有以下优势：

⚡ 轻量快速：搜索索引在构建时生成，客户端零负担
🎯 精准搜索：支持中文分词，搜索结果准确
🎨 界面美观：提供优雅的搜索弹窗界面
📱 响应式设计：完美适配桌面端和移动端
🔧 易于集成：与 Astro 框架无缝集成

✨ 功能特性

🔍 搜索功能

全文搜索：支持文档标题、正文内容的搜索
实时搜索：输入关键词后自动显示搜索结果
结果高亮：搜索关键词在结果中高亮显示
键盘导航：支持键盘上下键选择搜索结果

🎨 界面特性

玻璃拟态设计：采用现代玻璃质感设计风格
暗色模式：自动适配系统的暗色模式
动画效果：流畅的打开/关闭动画
移动端适配：全屏弹窗，触摸友好

⚙️ 安装配置

📦 安装依赖

npm install pagefind @pagefind/default-ui --save-dev

🔨 构建配置

在 package.json 中添加构建脚本：

{
  "scripts": {
    "build": "astro build && npm run pagefind",
    "pagefind": "pagefind --site dist"
  }
}

📝 配置文件

创建 pagefind.yml 配置文件：

# 站点源文件目录
site: dist

# 输出索引文件的目录
output_subdir: pagefind

# 要索引的内容选择器
root_selector: "[data-pagefind-body]"

# 排除的选择器
exclude_selectors:
  - "nav"
  - ".navbar"
  - "footer"
  - "script"
  - "style"

# 语言设置
language: zh

# 是否索引隐藏元素
index_hidden: true

🏷️ 页面标记

在文档页面的模板中添加搜索索引标记：

<!-- Pagefind 搜索索引内容 -->
<div data-pagefind-body style="display: none;" aria-hidden="true">
  <h1 data-pagefind-meta="title">{文档标题}</h1>
  <p data-pagefind-meta="description">{文档描述}</p>
  <div>{文档内容}</div>
</div>

📝 使用方法

🔓 打开搜索

有两种方式可以打开搜索弹窗：

点击搜索按钮：点击导航栏中的搜索图标按钮
快捷键：按 Ctrl + K（Windows/Linux）或 Cmd + K（Mac）

🔎 进行搜索

在搜索框中输入关键词
搜索结果会实时显示在下方
点击结果或按 Enter 键跳转到对应文档

🧭 导航搜索结果

↑ / ↓：在搜索结果中上下移动
Enter：打开选中的搜索结果
Esc：关闭搜索弹窗

⌨️ 快捷键

快捷键	功能
`Ctrl + K`	打开搜索弹窗
`↑` / `↓`	导航搜索结果
`Enter`	打开选中的结果
`Esc`	关闭搜索弹窗

🔎 搜索技巧

📝 基础搜索

直接输入关键词即可搜索：

语法

🔗 多关键词搜索

使用空格分隔多个关键词：

代码块 语法

💡 搜索建议

使用更具体的关键词获得更精准的结果
可以搜索文档标题或正文中的任意文字
支持中文搜索

❓ 常见问题

❓ Q: 为什么搜索不到内容？

A: 请检查以下几点：

是否已运行 npm run build 生成搜索索引
检查 dist/pagefind 目录是否存在索引文件
确认页面模板中已添加 data-pagefind-body 属性

❓ Q: 搜索结果中的链接多了 index.html？

A: 系统已自动处理，点击搜索结果会跳转到干净的 URL（如 /quick-start/ 而非 /quick-start/index.html）。

❓ Q: 如何在本地测试搜索功能？

A: 执行以下步骤：

# 1. 构建项目（包含搜索索引）
npm run build

# 2. 启动预览服务器
npm run preview

# 3. 在浏览器中访问 http://localhost:4321

❓ Q: 搜索索引多久更新一次？

A: 搜索索引在每次构建时重新生成。发布新文档或修改现有文档后，需要重新运行 npm run build。

❓ Q: 支持哪些文件格式的搜索？

A: 目前支持所有 Markdown 文档的搜索，包括：

基础语法文档
代码示例文档
配置说明文档
问题解决方案

🔧 技术细节

🔄 搜索索引生成流程

构建阶段：Astro 构建生成静态 HTML 文件
索引阶段：Pagefind 扫描 HTML 文件生成搜索索引
部署阶段：索引文件随网站一起部署

📁 索引文件位置

dist/
├── pagefind/
│   ├── pagefind.js          # 搜索核心库
│   ├── pagefind-highlight.js # 高亮插件
│   └── index/
│       └── zh-cn/           # 中文索引
└── ...

📝 更新日志

📅 2026-04-05

✨ 集成 Pagefind 搜索插件
🎨 设计搜索弹窗界面
⌨️ 添加键盘快捷键支持
📱 适配移动端显示

🔗 相关链接

💡 提示：如有问题或建议，欢迎提交 Issue 或 Pull Request。