#静态站搜索的三条路

方案 成本 适合规模 缺点
第三方服务(Algolia 等) 需要账号、有免费额度 任意 引入外部依赖,索引要同步
全量构建索引(Pagefind) 构建期多一步 几千页以上 中文分词支持一般
自己生成 JSON 索引 + 前端过滤 几十行代码 几百篇以内 只能做子串匹配

博客目前几十篇,第三种足够。判断标准很简单:索引文件能不能在 100 KB 以内。 超过这个量,首次打开搜索的延迟会被感知到,该换 Pagefind 了。

#第一步:构建时生成索引

在 build.mjs 里,把每篇文章的摘要信息写成一个数组:

JavaScript
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 就是纯粹的浪费。

JavaScript
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 面板里会看到重复的请求,然后开始怀疑自己。

失败也要兜底成空数组——搜索挂了不应该让整个页面报错。

#第三步:匹配与高亮

JavaScript
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 的编译开销比扫描本身还大。

高亮要小心两件事:

JavaScript
const highlight = (text, q) => {
  // 1. 先转义 HTML,否则文章标题里的 < 会把结构打乱
  const safe = text.replace(/[&<>]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;' }[c]));
  if (!q) return safe;
  // 2. 关键词也要转义,否则用户输入 "(" 直接让正则抛错
  const re = new RegExp(`(${q.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')})`, 'gi');
  return safe.replace(re, '<mark>$1</mark>');
};

顺序不能反:先转义内容,再插入标签。反过来会把标签本身也转义掉,页面上直接显示 <mark> 字面量。这个 bug 我写过两次。

#第四步:键盘操作

搜索框如果不支持键盘,就不算做完。

JavaScript
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 跳到第一条结果:

JavaScript
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 再补:

JavaScript
const debounce = (fn, ms = 120) => {
  let t;
  return (...args) => { clearTimeout(t); t = setTimeout(() => fn(...args), ms); };
};

打开时锁滚动。 面板是全屏遮罩,背景还能滚动就会很怪:

JavaScript
document.body.style.overflow = 'hidden';  // 打开
document.body.style.overflow = '';        // 关闭

别忘了在关闭路径上还原——包括点遮罩、按 Esc、点击结果跳转(跳转时其实会重新加载页面,但用 pushState 的站点就不会)。

#什么时候该换方案

给三个明确的切换信号:

  1. 索引超过 150 KB,首次搜索有可感知的卡顿;
  2. 需要全文检索,用户开始搜句子片段而不是关键词;
  3. 需要中文分词,includes 对「性能优化」这种词只能整体匹配,搜「优化」匹配不到——这时候该上 Pagefind 或者服务端方案了。

在那之前,120 行代码的方案性价比高得离谱:没有外部依赖、没有额度限制、没有隐私问题,所有计算都在用户自己的浏览器里完成。

#完整实现的目录结构

CODE
public/
├── assets/app.js          # 搜索逻辑(约 90 行)
└── search-index.json      # 构建产物
scripts/build.mjs          # 生成索引

就这些。没有服务端、没有数据库、没有 API 密钥。