# SSG 集成实践

URL: https://caijiao.org/pagefind/tutorial-08-ssg-integration
Source: docs/pagefind/tutorial-08-ssg-integration.md
Description: 以自定义静态站点生成器、VitePress、Astro、Hugo 等场景为例，讲解 Pagefind 的构建顺序、输出目录、客户端接入和部署注意事项。

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

## 通用构建脚本

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

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

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

这样浏览器就可以加载：

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

## 控制正文区域

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

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

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

## 当前项目的集成方式

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

```ts
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_*` 等索引资源。