Pagefind 静态搜索集成：让博客拥有全局搜索

#pagefind#搜索#astro
Pagefind 静态搜索集成：让博客拥有全局搜索

为什么选 Pagefind

静态站点搜索的常见方案有 Algolia、Lunr、Fuse.js 等，但 Pagefind 有几个独特优势：

  • 零后端：索引在构建时生成，搜索在浏览器端完成，不需要任何服务端
  • 按需加载：只有用户真正搜索时才加载索引分片，首屏体积几乎为零
  • 中文友好：内置中文分词，不需要额外配置
  • 自带 UI：提供开箱即用的搜索组件，也支持深度定制

集成步骤

安装

npm install -D astro-pagefind

配置

在 astro.config.mjs 中加入集成：

import pagefind from 'astro-pagefind';

export default defineConfig({
  integrations: [pagefind()],
});

集成会在 astro:build:done 钩子中自动运行 Pagefind CLI，对 dist/ 目录建索引， 输出到 dist/pagefind/。所以 npm run build 一条命令就够了。

加载 UI

Pagefind 的 UI 脚本和样式在 /pagefind/pagefind-ui.js 和 /pagefind/pagefind-ui.css， 可以在弹窗打开时动态加载：

const body = document.getElementById('search-modal-body');
await loadScript('/pagefind/pagefind-ui.js');
new window.PagefindUI({
  element: body,
  showSubResults: true,
  translations: { placeholder: '搜索文章…' },
});

主题定制

Pagefind UI 暴露了一组 CSS 变量，覆盖即可换肤：

.pagefind-ui {
  --pagefind-ui-primary: #4ade80;    /* 高亮色 → 薄荷绿 */
  --pagefind-ui-background: transparent; /* 透明背景，透出毛玻璃卡片 */
  --pagefind-ui-border: rgb(255 255 255 / 0.45);
  --pagefind-ui-border-radius: 14px;
}

配合 backdrop-blur 的弹窗容器，搜索结果会自然融入毛玻璃主题。

开发模式注意

开发模式下 Pagefind 索引不存在（它在 dist/ 里，不在 dev server 中）。 所以需要先跑一次 npm run build，之后 npm run preview 才能体验搜索。