#静态站搜索的三条路
| 方案 | 成本 | 适合规模 | 缺点 |
|---|---|---|---|
| 第三方服务(Algolia 等) | 需要账号、有免费额度 | 任意 | 引入外部依赖,索引要同步 |
| 全量构建索引(Pagefind) | 构建期多一步 | 几千页以上 | 中文分词支持一般 |
| 自己生成 JSON 索引 + 前端过滤 | 几十行代码 | 几百篇以内 | 只能做子串匹配 |
博客目前几十篇,第三种足够。判断标准很简单:索引文件能不能在 100 KB 以内。 超过这个量,首次打开搜索的延迟会被感知到,该换 Pagefind 了。
#第一步:构建时生成索引
在 build.mjs 里,把每篇文章的摘要信息写成一个数组:
export function searchIndexJson(posts) {
return JSON.stringify(
posts.map((p) => ({
title: p.title,
url: `/posts/${p.slug}.html`,
desc: p.excerpt,
date: p.date,
tags: p.tags.map((t) => t.name),
cover: p.cover
}))
);
}
几个刻意的取舍:
- 不索引正文。 全文索引体积会涨 10 倍以上,而博客场景下摘要加标签已经能覆盖大部分查询意图;
- 带封面。 搜索结果里有缩略图,视觉上更容易扫读;
- 不压缩字段名。 用
title而不是t,省下的几 KB 不值得牺牲可读性。
当前 6 篇文章的索引大约 2.4 KB。按这个体量,300 篇在 120 KB 上下,仍然在一次请求能接受的范围内。
#第二步:按需加载,不要放在首屏
索引绝对不能和主脚本一起加载。用户可能压根不搜索,那这几百 KB 就是纯粹的浪费。
let indexData = null;
let loading = null;
const loadIndex = () => {
if (indexData) return Promise.resolve(indexData);
if (!loading) {
loading = fetch('/search-index.json')
.then((r) => r.json())
.then((data) => { indexData = data; return data; })
.catch(() => { indexData = []; return []; });
}
return loading;
};
loading 这个中间变量的作用是合并并发请求。用户连点两下搜索按钮,或者输入触发得很快,没有它就会发两次请求。这是个很小的细节,但少了它,你在 Network 面板里会看到重复的请求,然后开始怀疑自己。
失败也要兜底成空数组——搜索挂了不应该让整个页面报错。
#第三步:匹配与高亮
const search = async (q) => {
const data = await loadIndex();
const keyword = q.trim().toLowerCase();
const hits = data.filter((p) => {
const hay = `${p.title} ${p.desc} ${p.tags.join(' ')}`.toLowerCase();
return hay.includes(keyword);
});
renderResults(hits.slice(0, 20), q.trim());
};
includes 是最笨的匹配方式,但也是最快的实现——几百条数据下,一次全表扫描不到 1 毫秒。不要在这里用正则,new RegExp 的编译开销比扫描本身还大。
高亮要小心两件事:
const highlight = (text, q) => {
// 1. 先转义 HTML,否则文章标题里的 < 会把结构打乱
const safe = text.replace(/[&<>]/g, (c) => ({ '&': '&', '<': '<', '>': '>' }[c]));
if (!q) return safe;
// 2. 关键词也要转义,否则用户输入 "(" 直接让正则抛错
const re = new RegExp(`(${q.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')})`, 'gi');
return safe.replace(re, '<mark>$1</mark>');
};
顺序不能反:先转义内容,再插入标签。反过来会把标签本身也转义掉,页面上直接显示 <mark> 字面量。这个 bug 我写过两次。
#第四步:键盘操作
搜索框如果不支持键盘,就不算做完。
document.addEventListener('keydown', (e) => {
const typing = /input|textarea/i.test(document.activeElement?.tagName || '');
if (e.key === '/' && !typing) { e.preventDefault(); openSearch(); }
if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === 'k') { openSearch(); }
});
typing 这个判断必须有。否则用户在评论框(如果有)里打斜杠,焦点会被抢走,体验立刻崩坏。
面板打开后,Esc 关闭、Enter 跳到第一条结果:
panel.addEventListener('keydown', (e) => {
if (e.key === 'Escape') closeSearch();
if (e.key === 'Enter') {
const first = panel.querySelector('.search-result');
if (first) location.href = first.getAttribute('href');
}
});
#两个容易被忽略的细节
输入防抖。 索引小的时候,每次按键都过滤反而更「跟手」;索引大了之后必须防抖。我的做法是先不防抖,等索引超过 200 KB 再补:
const debounce = (fn, ms = 120) => {
let t;
return (...args) => { clearTimeout(t); t = setTimeout(() => fn(...args), ms); };
};
打开时锁滚动。 面板是全屏遮罩,背景还能滚动就会很怪:
document.body.style.overflow = 'hidden'; // 打开
document.body.style.overflow = ''; // 关闭
别忘了在关闭路径上还原——包括点遮罩、按 Esc、点击结果跳转(跳转时其实会重新加载页面,但用 pushState 的站点就不会)。
#什么时候该换方案
给三个明确的切换信号:
- 索引超过 150 KB,首次搜索有可感知的卡顿;
- 需要全文检索,用户开始搜句子片段而不是关键词;
- 需要中文分词,
includes对「性能优化」这种词只能整体匹配,搜「优化」匹配不到——这时候该上 Pagefind 或者服务端方案了。
在那之前,120 行代码的方案性价比高得离谱:没有外部依赖、没有额度限制、没有隐私问题,所有计算都在用户自己的浏览器里完成。
#完整实现的目录结构
public/
├── assets/app.js # 搜索逻辑(约 90 行)
└── search-index.json # 构建产物
scripts/build.mjs # 生成索引
就这些。没有服务端、没有数据库、没有 API 密钥。