pagefind 适合结构清晰、千页以内且不依赖复杂前端框架的静态站点，支持中文分词但需显式配置--language zh和html lang属性，索引仅覆盖渲染文本，需规避动态内容与OOM风险，并通过CI策略优化重建效率。
pagefind 是否适合你的静态站点
如果你的静态 HTML 站点结构清晰、文件数量在 1000 页以内、不依赖复杂前端框架（如 React/Vue SSR），pagefind 是目前最省心的选择。它不侵入源码、不改构建流程、生成纯静态索引，且支持中文分词（需启用 --language zh）。但要注意：它只索引页面中实际渲染的文本内容，会自动跳过 <script>、<style>、<textarea> 和注释；若你用 data-* 属性或 JS 动态注入关键内容，这些不会被收录。
如何避免索引体积爆炸和内存溢出
默认情况下，pagefind 会对所有 HTML 文件全量解析并构建倒排索引，当文档超 2000+ 页或含大量 PDF/Markdown 原文嵌入时，Node.js 进程容易 OOM。解决方法是：
- 用
--glob "**/*.html"显式限定范围，排除_site/archive/或drafts/类目录 - 通过
--bundle-dir _pagefind_min指定更短路径，减少生成的 JS 文件 URL 长度 - 加
--no-spa关闭单页应用模式（除非你真用了 History API 路由） - 对超大站，先运行
pagefind --source public --dry-run查看预估索引大小和耗时
中文检索不准？检查这三处配置
pagefind 默认按空格切词，对中文几乎无效。必须手动干预：
- 确保 CLI 中明确指定
--language zh（不是zh-CN或其他变体） - HTML 页面
<html lang="zh">属性要存在，否则部分语言检测逻辑会 fallback 到英文 - 若仍匹配生硬（如“数据库”拆成“数据”“库”），可在页面中添加
<meta name="pagefind-weight" content="3">提升标题区域权重，或用data-pagefind-body属性限定正文范围，避免页脚导航词污染索引
增量重建与 CI/CD 集成的关键细节
pagefind 不原生支持增量索引，每次运行都是全量重建。但在 CI 流程中可规避重复工作：
立即学习“前端免费学习笔记（深入）”；
- 把
_pagefind目录加入.gitignore，但保留其结构快照（如_pagefind/manifest.json）用于 diff - 用
git diff --name-only HEAD^ HEAD -- public/ | grep '\.html$'获取本次变更的 HTML 文件列表 - 仅对这些文件重新运行
pagefind --source public --only-changed（需配合自定义 wrapper 脚本，官方暂未内置该 flag） - 真正上线前，仍建议 nightly 全量重建一次，防止 manifest 错位或缓存残留
注意：_pagefind 里的 index.html 是查询 UI，而 data.js 是核心索引数据——后者体积随文档增长线性上升，10 万页可能达 200MB，务必确认 CDN 支持 Brotli 压缩且缓存策略合理。
