# Prompt-to-PR：为Astro站点添加Pagefind搜索

> 完整的标准操作流程——从首次提示到PR描述，为Astro站点添加静态、无后端搜索功能。

**Type:** Playbook  
**Tools:** Cursor, Claude Code  
**Stack:** Astro, TypeScript  
**Difficulty:** easy  
**Updated:** 2026-06-08

---

完整的操作手册：需求、首次提示、预期变更、审查、测试、
常见失败、修复提示以及PR描述。

## 1. 需求

为静态Astro站点添加全文搜索，无需服务器和数据库。

## 2. 首次提示

```txt title="First Prompt"
Add Pagefind search to this Astro static site.

- Add `pagefind` as a devDependency.
- Update the build script to run `astro build && pagefind --site dist`.
- Create a `/search` page that mounts Pagefind UI from `/pagefind/pagefind-ui.js`.
- Mark the main article body with `data-pagefind-body` and add
  `data-pagefind-ignore` to nav/footer.
- Do not introduce a server adapter; this stays fully static.
```

## 3. 预期文件变更

```txt
package.json                 (build script)
src/pages/search.astro       (new)
src/layouts/BaseLayout.astro (data-pagefind-ignore on chrome)
```

## 4. 审查清单

- 构建脚本在 `astro build` *之后*运行Pagefind。
- 搜索页面在 `astro dev` 中优雅降级（索引仅在构建后存在）。
- 导航/页脚被排除在索引之外。

## 5. 测试命令

```bash
bun run build
bun run preview
# open /search and query a known term
```

## 6. 常见失败

- 在脚本加载前挂载Pagefind UI → `PagefindUI is not defined`。
- 在构建前运行Pagefind，导致索引为空。

## 7. 修复提示

```txt title="Fix Prompt"
Pagefind indexed an empty site. Ensure the build runs `astro build` first,
then `pagefind --site dist`, and that the UI script loads before init.
```

## 8. PR描述

```md title="PR description"
Add static full-text search via Pagefind. Indexes `dist` at build time;
no backend. New `/search` page; nav/footer excluded from the index.
```