SSG 集成实践

Pagefind 最适合接在静态站点生成器之后。无论你使用 VitePress、Astro、Hugo、Eleventy，还是自研 SSG，关键点都是：先生成 HTML，再运行 Pagefind。

通用构建脚本

{
  "scripts": {
    "build": "your-ssg-build && pagefind --site dist"
  }
}

如果搜索资源需要输出到固定路径：

pagefind --site dist --output-path dist/_pagefind

这样浏览器就可以加载：

const pagefind = await import("/_pagefind/pagefind.js");

控制正文区域

自研 SSG 或 Vue SSR 外壳通常会输出统一布局。推荐只给正文主区域加 data-pagefind-body：

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

导航、侧边栏、目录、页脚和广告位不应进入正文索引。若它们必须存在于 main 中，可给局部元素加 data-pagefind-ignore。

当前项目的集成方式

本项目的构建流程已经在静态页面输出后运行 Pagefind：

await execFileAsync(command, [
  "exec",
  "pagefind",
  "--site",
  "dist",
  "--output-path",
  "dist/_pagefind",
  "--root-selector",
  "main",
  "--force-language",
  "zh",
]);

页面正文位于带有 data-pagefind-body 的 main 中，客户端搜索框按需导入 /_pagefind/pagefind.js，并使用 pagefind.search(query) 获取结果。

这种方式的好处是：

• Pagefind 不参与 Markdown 编译链路。
• 搜索索引来自最终 HTML，和线上内容一致。
• 搜索资源放在 dist/_pagefind，部署时作为静态资源一起发布。
• 中文站点用 --force-language zh 保持统一索引。

部署检查

上线前检查：

• 构建产物中存在 dist/_pagefind/pagefind.js。
• 页面能访问 /_pagefind/pagefind.js。
• 搜索框只在用户交互时加载 Pagefind。
• 搜索结果 URL 与站点路由一致。
• CDN 或静态托管没有屏蔽 .wasm、.pf_* 等索引资源。