站点搜索别再只靠关键词匹配了，Kent C. Dodds 这套混合搜索方案值得每个内容站抄过去

站点搜索别再只靠关键词匹配了，Kent C. Dodds 这套混合搜索方案值得每个内容站抄过去

导语

做个人博客、文档站、内容平台的人都知道，搜索是个老大难问题：纯关键词匹配容易漏掉同义表达，纯语义搜索又经常把不相关的内容排前面，结果用户搜了半天找不到想要的东西。Kent C. Dodds 今年 3 月发了一篇 “Implementing Hybrid Semantic + Lexical Search”，把他博客里的搜索系统从纯词法升级成混合搜索的完整过程讲清楚了。这不是什么论文里的理想方案，而是一个真实运行中的博客站点，代码和工程决策都在文章里。如果你正在给站点加搜索，或者对”语义搜索到底该怎么落地”有疑问，这篇文章直接能抄。

正文

问题：为什么站内搜索总是”搜不准”？

大多数站点的搜索逻辑其实很简单：把文章标题和内容切成词，建立倒排索引，用户搜什么就匹配什么。这种方案叫词法搜索（lexical search），好处是实现简单、速度快、结果可控，但问题是它只认 exact match 或 near match，不懂同义词、不懂上下文、不懂用户的真实意图。

具体表现就是：

• 搜 “React hooks”，找不到写了 “useState” 和 “useEffect” 的文章
• 搜 “dark mode”，找不到标题里写的是 “dark theme” 的文章
• 搜 “performance”，返回一堆包含这个词但主题完全无关的页面

反过来，纯语义搜索（semantic search）用 embedding 向量匹配，能理解语义相似度，但它也有问题：容易把主题相近但实际不相关的内容排上来，而且对专有名词、代码片段、具体技术术语的匹配精度往往不如词法搜索。

Kent C. Dodds 遇到的问题也一样：他的博客有几百篇文章，纯词法搜索已经不够用，但纯语义搜索又不够准。于是他做了个混合方案：词法搜索保证精确匹配，语义搜索补足意图理解，再把两者的结果按权重合并。

方案：混合搜索的工程实现

混合搜索的核心思路是：不是二选一，而是让两个系统各管一段，再把结果合并。

Kent 的实现里有几个关键决策值得参考：

第一，词法搜索用 FlexSearch，不用 Elasticsearch/Lunr.js。

FlexSearch 是一个轻量级的全文搜索库，体积小、速度快，对前端站点来说足够用。他的选择逻辑很直接：站点内容量不大，不需要分布式搜索引擎的复杂能力，一个能在浏览器端跑的库就能解决问题。

第二，语义搜索用 embedding + 向量检索，但不追求 100% 覆盖。

他的做法是给每篇文章生成 embedding，然后在用户搜索时把 query 也转成 embedding，用余弦相似度找最相似的文章。但这里有个工程取舍：他并不是对所有文章都做语义索引，而是优先给标题、摘要、标签这些高价值文本做 embedding，长正文反而没全量进向量库。

这个取舍很实际：embedding 计算和存储都有成本，而且长正文的语义信息密度不一定比标题高。与其全量塞进去让结果变水，不如先保证核心元数据的语义匹配质量。

第三，合并策略用加权排序，不是简单拼接。

两个搜索系统返回的结果怎么合并？Kent 的做法是给每个结果一个综合得分，词法得分和语义得分按权重加权，然后再排序。权重不是拍脑袋定的，而是根据实际搜索结果调出来的。

他的具体思路是：如果用户的查询很像一个精确的关键词（比如 “React useEffect”），就提高词法搜索的权重；如果查询更像一个自然语言问句（比如 “how to handle side effects in React”），就提高语义搜索的权重。这个动态权重调整是混合搜索能不能”真的变好”的关键。

代码层面：一个可落地的简化版

虽然 Kent 的完整实现代码都在他博客文章里，但核心逻辑可以简化成这样：

// 1. 词法搜索：用 FlexSearch 建立索引
const flexIndex = new FlexSearch.Index({
  tokenize: "forward",
  resolution: 9
});

documents.forEach(doc => {
  flexIndex.add(doc.id, `${doc.title} ${doc.tags.join(" ")}`);
});

// 2. 语义搜索：给 query 和文档生成 embedding
const queryEmbedding = await generateEmbedding(query);
const docEmbeddings = await getDocumentEmbeddings();

// 3. 分别搜索
const lexicalResults = flexIndex.search(query);
const semanticResults = await vectorSearch(queryEmbedding, docEmbeddings);

// 4. 合并排序
const merged = mergeResults(lexicalResults, semanticResults, {
  lexicalWeight: queryIsKeyword ? 0.7 : 0.3,
  semanticWeight: queryIsQuestion ? 0.7 : 0.3
});

这段代码省略了 embedding 生成的具体实现和向量检索的细节，但逻辑是通的：两个独立的搜索通道，各自返回结果，最后用加权合并。

Kent 在文章里还提到了几个工程细节，比如 embedding 模型的选择、向量数据库的选型、索引更新的时机。这些内容在他的博客文章里有更完整的讨论，如果你要自己搭一套，建议先读原文再看代码。

工程取舍：混合搜索不是银弹

Kent 自己也提到，混合搜索不是对所有站点都适用。如果你的站点内容很少，纯词法搜索就够了；如果你的内容是专业领域且术语密集，可能需要额外的术语表来辅助语义匹配。

几个需要自己判断的点：

• 内容量级：几十篇文章没必要上 embedding，几百篇以上可以考虑
• 查询类型：如果你的用户主要是搜具体术语、函数名、报错信息，词法搜索权重应该更高
• 性能预算：语义搜索涉及 embedding 计算，首次加载可能有延迟，要做好 loading 状态
• 维护成本：混合系统比单一系统复杂，出了问题排查难度也更高

他的结论是：对于内容站点来说，混合搜索的 ROI 是正的，因为词法搜索兜底了精确匹配，语义搜索补上了意图理解，两者结合后的体验明显优于单一方案。

对其他前端项目的启示

这篇文章的价值不只是”怎么实现混合搜索”，更重要的是它展示了一个工程决策的思考过程：不是追最新技术，而是根据实际问题的特点选择合适的技术组合。

对前端工程师来说，Kent 的这篇实现至少给了三个可以直接借鉴的思路：

1. 站内搜索的优先级被低估了。很多项目做到一半才发现搜索体验很差，但这时候再重构成本很高。如果一开始就规划好搜索架构，后续会省很多事。

2. 轻量方案优先。FlexSearch 能在前端跑，就不要一开始就上 Elasticsearch；embedding 能用小模型就别硬上大模型。工程化的核心是在够用的前提下尽量简单。

3. 混合架构比单一架构更稳。词法 + 语义的混合，本质上是用两个不完美的系统互补，最终结果比任何一个单独系统都好。这种思路不只适用于搜索，也适用于很多其他工程场景。

收尾

如果你的站点正在做搜索，或者计划加搜索，Kent C. Dodds 的这篇文章值得放在待读清单的第一位。判断标准很简单：如果你发现用户抱怨”搜不到”的次数越来越多，而且纯关键词优化已经没法解决，那就是该考虑混合搜索的时候了。