用户搜不到东西，就会以为你的产品是空的：vibe 项目的站内搜索实战

用户搜不到东西，就会以为你的产品是空的

我见过太多 vibe coding 做出来的项目死在同一个地方：作者熬了几个通宵，塞进去几百条内容、几十个功能，上线后用户进来的第一件事就是点开搜索框，敲几个字，回车，然后看到一句「没有找到结果」，扭头就走。

问题不在内容。问题在用户永远走不到内容面前。你用 AI 生成的 CRUD 骨架里，默认是没有搜索的——不是搜索做得差，是根本没有搜索。Cursor、Claude Code 这些工具给你生成的列表页，一般都只有「全部加载出来」和「按创建时间倒序」两招。内容一过百条，这个页面就变成了一口枯井：东西都在水底下，但用户打不上来。

这件事的心理机制很残酷：用户不会想「这个产品的搜索很弱」，他会想「这个产品没什么东西」。搜索框是用户对产品内容密度的第一个探测器。搜得到，产品就显得深；搜不到，产品就显得空。你花一个月攒的内容，可能因为缺一个搜索框而被判了死刑。

好消息是：给一人小项目加上「够用且体验不错」的站内搜索，真实工作量大概是一个周末。它不需要你成为搜索引擎专家，只需要你理解三层心智模型、做对一次方案选型、再把几个体验细节打磨到位。这篇文章就是这件事的完整实战手册。

一个值得先想清楚的问题：你的内容配得上搜索吗

在动手之前，先泼一盆冷水。搜索解决的是「找到」的问题，但它有个前提：值得被找到的东西得先存在。如果你的项目只有 20 条内容，搜索框就是摆设——用户一眼能翻完的列表，不需要搜索。这时候把时间花在搜索上，是典型的过早优化。

经验法则是：内容过 100 条，或者用户第二次访问时明显在「找」而不是在「逛」，就是该加搜索的信号。100 条是个魔法数字：少于它，滚动几下就到底了；多于它，用户开始依赖记忆和运气，而运气是最不可靠的导航。

还有一个反直觉的判断：搜索框本身会改变用户行为。有了好用的搜索，用户会从「浏览模式」切换到「检索模式」——他不再耐心翻你的分类和推荐，而是直接要答案。这意味着搜索上线后，你的内容标题写法都得跟着变：标题要包含用户会搜的词，而不是你觉得文艺的词。「我的拉面之旅」不如「东京拉面三日游攻略」好被搜到。搜索不仅是一个功能，它会反过来塑造你的内容生产方式。

心智模型：搜索只有三层

把「站内搜索」这个大词拆开，它其实只有三层，每一层解决一个问题：

1. 索引层：把内容变成可被快速查找的结构。数据库里存的是一整段文本，搜索需要的是「哪个词出现在哪条记录里」的倒排关系。没有索引，每次搜索都是全表 LIKE 扫描——数据量一过万就慢到不可用。
2. 查询层：把用户的输入变成一次有效的查找。包括分词（中文必须解决「拉面」是一个词还是「拉」+「面」）、容错（用户打错字怎么办）、权重（标题命中和正文命中该不该同等对待）。
3. 呈现层：把结果交到用户手上。排序、高亮关键词、空状态、联想建议——这一层决定了用户觉得你的搜索「聪明」还是「笨」。

记住这个三层模型，后面所有选型争论都会变得清晰：Postgres 全文搜索和 Typesense 的区别，本质上是「把索引层和查询层放在哪里」的取舍；Algolia 贵，贵的是它把三层全替你做完了。

方案选型：四选一，先看这张表

一人项目的选型逻辑和大公司完全不同。大公司选型看 QPS 和 SLA，你选型只看三件事：成本、运维负担、中文支持。我把四个主流方案按这三个维度摊开：

方案	成本	运维	中文分词	适合谁
Postgres 全文搜索（tsvector）	0（数据库本来就有）	0（零新增组件）	原生不支持，需 pg_jieba 扩展或应用层分词	已经在用 Postgres、内容在万级以下、以中文为主但能接受分词折中方案的项目
Typesense	0（自托管开源）	低（单个 Docker 容器，资源占用小）	内置支持尚可，CJK 分词开箱可用（以官方文档为准）	想要「开箱即用的搜索体验」（容错、高亮、联想）又不想付 Algolia 钱的项目
Meilisearch	0（自托管开源）	低（单个二进制，部署极简）	支持中文，但精细度一般（以官方文档为准）	和 Typesense 同一生态位；API 设计更 REST 直觉，个人偏好成分大
Algolia	免费额度后按量付费，一人项目月费通常在几十美元量级	0（全托管）	好，官方维护的中文支持	搜索是核心卖点、愿意为体验付费、且不想碰运维的项目

我的判断很直接：90% 的 vibe 小项目应该在 Postgres 全文搜索和 Typesense 之间二选一。Algolia 的体验确实是最好的，但它的定价是按搜索次数和记录数算的，一人项目的流量曲线很抖，一个被分享到社交媒体的帖子就能让你收到意外账单——除非搜索就是你的护城河，否则别在早期给自己加一个按量计费的依赖。Meilisearch 和 Typesense 二选一更多是口味问题，我这篇用 Typesense 举例，因为它的 typo tolerance（拼写容错）和 instantsearch 生态对新手更友好。

选 Postgres 还是 Typesense，一句话决策：如果你的内容已经在 Postgres 里、搜索需求是「能搜到就行」，选 Postgres tsvector，半天搞定；如果你想要「搜起来感觉很聪明」（打错字也能找到、输入即有联想），加一个 Typesense 容器，一个周末搞定。

关于 Algolia 再多说两句，因为它是新手最容易踩的坑：它的免费额度看起来很慷慨，但计费维度是「搜索请求数 + 索引记录数」双轨制。一人项目的流量最不稳定的就是被社交媒体翻牌的那几天——平时一天几百次搜索，被转发后一小时就能烧掉一个月的额度。更隐蔽的是记录数：你把每条内容的多个字段、多个语言版本都塞进索引，记录数膨胀得比你想象快得多。按量计费的服务配上不可预测的流量，等于把定价权交给了运气。等你月收入稳定覆盖这笔开支再考虑它，在此之前，自托管方案的「固定成本」对独立开发者友好得多。

Typesense 和 Meilisearch 之间我再给一个选择依据：去看它们的 Dashboard。Typesense 自带一个开箱即用的管理后台，能直观看到索引、调搜索参数；Meilisearch 的同类功能相对弱一些。对一人团队来说，「不用写代码就能验证搜索效果」这个特性值很多钱——调 relevance 的过程就是不断试搜、看结果、改参数的循环，有个可视化后台能把这个循环从小时级压缩到分钟级。

实战一：Postgres tsvector，零新增组件的搜索

Postgres 的全文搜索很多人听说过但没真用过，觉得它是「玩具」。这个印象过时了。对于万级以下的数据量，配好 GIN 索引的 tsvector 查询是毫秒级的，瓶颈从来不在 Postgres，而在你没建索引。

第一步：migration 加上 tsvector 列和 GIN 索引

假设你有一张 posts 表，字段是 title 和 body。不要每次查询时现场 to_tsvector(title || ' ' || body)——那会让索引用不上。正确做法是加一个物化列，建 GIN 索引：

-- migration: add full-text search to posts
ALTER TABLE posts ADD COLUMN search_vector tsvector;

-- 回填已有数据：标题权重 A，正文权重 B
UPDATE posts SET search_vector =
  setweight(to_tsvector('english', coalesce(title, '')), 'A') ||
  setweight(to_tsvector('english', coalesce(body, '')), 'B');

-- GIN 索引，这是全文搜索性能的全部秘密
CREATE INDEX posts_search_vector_idx ON posts USING GIN (search_vector);

-- 新增/更新时自动维护 search_vector 的触发器
CREATE OR REPLACE FUNCTION posts_search_vector_trigger() RETURNS trigger AS $$
BEGIN
  NEW.search_vector :=
    setweight(to_tsvector('english', coalesce(NEW.title, '')), 'A') ||
    setweight(to_tsvector('english', coalesce(NEW.body, '')), 'B');
  RETURN NEW;
END
$$ LANGUAGE plpgsql;

CREATE TRIGGER posts_search_vector_update
  BEFORE INSERT OR UPDATE OF title, body ON posts
  FOR EACH ROW EXECUTE FUNCTION posts_search_vector_trigger();

注意触发器里写的是 BEFORE INSERT OR UPDATE OF title, body——限定列之后，其他字段的更新不会触发无意义的向量重算。这个小细节在内容频繁被点赞/更新计数时能省不少写放大。

第二步：中文分词怎么办

这是 Postgres 全文搜索唯一的硬伤：to_tsvector 的内置分词对中文基本等于没分，「我爱吃拉面」会被当成一整个 token。用户搜「拉面」就搜不到「我爱吃拉面」。三条路：

• pg_jieba 扩展：分词质量最好，查询时 to_tsvector('jieba', ...) 即可。代价是需要往数据库里装扩展——托管 Postgres（如 Supabase、Neon）不一定支持，先查你的服务商文档。
• 应用层分词后存入：写入时在应用层用结巴分词把文本切好、空格拼接，再喂给 to_tsvector('simple', ...)（simple 配置不做额外分词，原样接受）。这是最稳的折中方案，不依赖数据库扩展，Vercel + Neon 这种组合也能用。
• 中英混合的务实做法：如果内容是中英混合（vibe 项目很常见），应用层分词时保留英文原词，中文按词切分，统一小写，喂给 simple 配置。实测对博客、文档、商品标题这类场景完全够用。

我的建议：先用应用层分词方案上线。pg_jieba 是更优雅的解，但它把你和特定 Postgres 发行版绑死了；应用层分词多写二十行代码，换来的是任何 Postgres 都能跑。等你真的一天有上万次搜索再考虑迁到 pg_jieba。

第三步：查询语句，权重排序是灵魂

-- $1 是用户输入，先在应用层分词/清洗后再传进来
SELECT id, title,
       ts_rank(search_vector, query) AS rank
FROM posts, plainto_tsquery('simple', $1) AS query
WHERE search_vector @@ query
ORDER BY rank DESC
LIMIT 20;

几个要点：

• plainto_tsquery 会把用户输入当普通文本处理，自动做 AND 连接——用户敲「拉面 好吃」，两个词都必须命中。这比 to_tsquery 安全得多，后者会把用户输入里的 &、| 当运算符解析，是注入式 bug 的温床。
• ts_rank 配合前面 setweight 的 A/B 权重，标题命中的天然排在前面。排序是搜索体验的一半，没有权重的全文搜索等于把用户扔进结果堆里自己翻。
• 如果还想再进一步，可以把 ORDER BY rank DESC 改成按 rank 和发布时间/热度的加权组合——新内容在同等相关度下适当置顶，这是所有内容型产品的潜规则。
• Postgres 11+ 还提供了 websearch_to_tsquery，支持用户直觉里的 Google 语法：引号表示精确短语、减号表示排除。比如用户输入 "拉面" -东京，它能正确解析。这是 plainto_tsquery 的升级版，如果你的用户已经习惯了搜索引擎的语法，直接上这个，不用自己解析。

实战二：Typesense，一个 Docker 容器的「聪明搜索」

Postgres 方案解决的是「搜得到」，Typesense 解决的是「搜得爽」。它的杀手特性是三件套：拼写容错（typo tolerance）、输入即搜（instant search）、分面筛选（faceting），而且全是开箱即用的。对一人项目来说，最大的吸引力是运维成本：单个 Docker 容器，内存占用小，不需要调 JVM、不需要搭集群。

一行启动，建 collection

docker run -d --name typesense \
  -p 8108:8108 \
  -v /data/typesense:/data \
  -e TYPESENSE_API_KEY=your-admin-api-key \
  -e TYPESENSE_DATA_DIR=/data \
  typesense/typesense:27.1

然后定义 collection 的 schema（以官方文档为准，字段名随版本可能有调整）：

curl -X POST 'http://localhost:8108/collections' \
  -H "X-TYPESENSE-API-KEY: your-admin-api-key" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "posts",
    "fields": [
      {"name": "title", "type": "string"},
      {"name": "body", "type": "string"},
      {"name": "created_at", "type": "int64"}
    ],
    "default_sorting_field": "created_at"
  }'

数据同步：别手写，用数据库触发的思路

Typesense 不是你的主数据库，它只是一个搜索索引——主数据永远在 Postgres 里，Typesense 里只放「用来搜和用来展示」的字段。同步策略按数据量选：

• 小项目（万级以下）：写操作（创建/更新/删除内容）的 API 里顺手调 Typesense 的 upsert/delete。一行代码的事，别 over-engineer。
• 再大一点：用 Postgres 的 LISTEN/NOTIFY 或一个定时同步脚本做最终一致。搜索索引晚几秒更新，用户根本感知不到。

一个新手常犯的错误是把 Typesense 当主库用，往里塞完整对象。它是个搜索引擎，不是数据库——字段越精简，索引越小，搜索越快。

前端：instantsearch 接入，半小时出效果

Typesense 官方维护了 instantsearch 适配器，前端体验是「每敲一个字母结果就变」，这种即时反馈是用户觉得搜索「聪明」的最大来源：

import TypesenseInstantSearchAdapter from
  'typesense-instantsearch-adapter';
import { InstantSearch, SearchBox, Hits } from
  'react-instantsearch';

const adapter = new TypesenseInstantSearchAdapter({
  server: {
    apiKey: 'your-search-only-api-key', // 注意：只读 key，不能用 admin key
    nodes: [{ host: 'search.your-domain.com', port: 443, protocol: 'https' }],
  },
  additionalSearchParameters: { query_by: 'title,body' },
});
const searchClient = adapter.searchClient;

export function Search() {
  return (
    <InstantSearch searchClient={searchClient} indexName="posts">
      <SearchBox placeholder="搜索标题或正文…" />
      <Hits />
    </InstantSearch>
  );
}

安全红线：前端只能用 search-only API key。Typesense 支持按 key 做权限隔离（只能搜指定的 collection、不能写），admin key 泄露等于把索引的写权限送人。这个 key 放在前端代码里是预期用法，但一定是最小权限的那个。

体验细节：决定「聪明还是笨」的六件事

搜索引擎选对了只是及格。用户真正感知到的，是下面这六个细节。它们每一个都是小工程，但加起来就是「这个搜索真好用」和「这什么玩意儿」的区别。

1. 输入防抖：别让每次敲键都打一次查询

用户输入「拉面」是两个 keystroke，没有防抖就是两次查询——浪费资源不说，结果闪烁两次，体验很廉价。标准做法是 200-300ms 防抖：

import { useState, useEffect } from 'react';

// 通用防抖 hook：value 稳定 delay 毫秒后才真正更新
export function useDebounce<T>(value: T, delay = 250): T {
  const [debounced, setDebounced] = useState(value);
  useEffect(() => {
    const timer = setTimeout(() => setDebounced(value), delay);
    return () => clearTimeout(timer); // 新输入进来就取消上一次
  }, [value, delay]);
  return debounced;
}

// 用法：搜索框绑定 rawQuery，真正发请求用 debouncedQuery
const [rawQuery, setRawQuery] = useState('');
const debouncedQuery = useDebounce(rawQuery, 250);
useEffect(() => {
  if (debouncedQuery.trim()) fetchResults(debouncedQuery);
}, [debouncedQuery]);

2. 关键词高亮：让用户一眼看到「为什么是这条」

搜索结果里把命中的词标黄（或加粗），是成本最低、效果最显著的体验优化。它回答了用户心里的问题：「这条结果跟我搜的词有什么关系？」Typesense/Meilisearch 会在返回里直接给你 highlight 片段；Postgres 方案可以用 ts_headline：

SELECT id, title,
  ts_headline('simple', body, plainto_tsquery('simple', $1),
    'StartSel=<mark>, StopSel=</mark>, MaxFragments=2') AS snippet
FROM posts, plainto_tsquery('simple', $1) AS query
WHERE search_vector @@ query
ORDER BY ts_rank(search_vector, query) DESC
LIMIT 20;

注意 ts_headline 的参数里直接拼 HTML 标签是示例写法，生产环境记得做转义——搜索词来自用户输入，snippet 进 innerHTML 之前必须过一遍 XSS 过滤。

3. 空状态：没搜到时别只说「没有结果」

「没有找到结果」是搜索体验的坟场。好的空状态做三件事：承认、建议、给出口。「没找到『拉面』，试试『面条』？」+ 几个热门搜索词 + 回首页的按钮。成本是半小时，效果是用户少流失一半。

这里有个进阶技巧：零结果页面是全站转化率最高的广告位之一。用户在这个页面上的意图极其明确——他想要某样东西而你没有。与其放一句干巴巴的道歉，不如放「订阅这个关键词，有新内容时通知你」的功能。对内容型产品，这一个小功能沉淀下来的订阅关系，长期价值超过搜索本身。很多 newsletter 产品就是这么冷启动的：先让用户搜，搜不到就订阅，等内容攒够了再通知回来。

4. 拼写纠错：「拉画」也该找到「拉面」

中文输入法联想词按错、拼音打错，是中文搜索最常见的失败原因。Typesense 的 typo tolerance 开箱即用；Postgres 方案可以配 pg_trgm 扩展做模糊匹配兜底：

-- pg_trgm：三元组相似度，拼写纠错的廉价方案
CREATE EXTENSION IF NOT EXISTS pg_trgm;
CREATE INDEX posts_title_trgm_idx ON posts USING GIN (title gin_trgm_ops);

-- 相似度大于 0.3 即视为命中（阈值按数据调）
SELECT id, title, similarity(title, $1) AS sml
FROM posts
WHERE title % $1
ORDER BY sml DESC
LIMIT 10;

实战策略：先跑全文搜索，有结果就直接返回；零结果时再跑一遍 trigram 模糊查询，并在 UI 上提示「是不是要找：XXX」。两层漏斗，既保 precision 又保 recall。

5. 搜索关键词分析：用户在用搜索告诉你他想要什么

这是被低估最多的环节。把用户的搜索词记下来（去重、记次数、记零结果率），每周看一次，你会得到一份免费的用户需求清单：搜得多但零结果的词，就是你该去生产的内容；搜得多的词，值得在首页给个入口。实现极简——搜索 API 里顺手写一条日志：

// Next.js search API route：记录搜索词（伪代码）
export async function GET(req: Request) {
  const q = new URL(req.url).searchParams.get('q')?.trim() ?? '';
  if (q.length >= 2) {
    // 异步记一笔，不阻塞搜索响应
    logSearchQuery(q).catch(() => {});
  }
  const results = await searchPosts(q);
  return Response.json({ results });
}

async function logSearchQuery(q: string) {
  // upsert：词已存在则次数+1，不存在则插入
  await db.$executeRaw`
    INSERT INTO search_logs (query, count, zero_result_count, updated_at)
    VALUES (${q}, 1, 0, NOW())
    ON CONFLICT (query) DO UPDATE
    SET count = search_logs.count + 1, updated_at = NOW()`;
}

隐私提醒：只记搜索词本身，别记「谁搜的」。一人项目没有法务部，但用户信任丢了比法务问题更致命。

6. 移动端：搜索框别藏在汉堡菜单里

超过一半流量来自手机，但很多 vibe 项目的移动端把搜索藏在二级菜单里。规则很简单：首屏可见，一点即搜。如果首页首屏放不下搜索框，说明首页的信息架构本身就有问题。

搜索的隐藏成本：索引不是免费的午餐

选型时大家都在算查询有多快，很少有人算索引有多贵。索引的隐藏成本有三笔账：

第一笔是写入放大。Postgres 方案里，每次更新标题或正文都要重算 tsvector 并更新 GIN 索引；Typesense 方案里，每次写操作都要多一次网络调用。内容更新频繁（比如点赞数、阅读数存在同一张表）的项目，要特别注意别让高频更新的字段触发索引重建——前面 migration 里触发器限定 OF title, body 就是这个原因。计数类字段单独放一张表，或者干脆不同步到搜索索引里。

第二笔是同步延迟的坑。用了外部搜索引擎，就有「主库和索引不一致」的时间窗口。用户刚发布一篇文章，立刻搜却搜不到，他会认为是 bug。对策不复杂：写操作成功后，前端乐观地把新内容插到本地结果列表里，不等索引同步完成。这个小技巧能掩盖掉 99% 的同步延迟体感。

第三笔是多语言。中英混合内容的分词策略要在一开始就定好，中途换分词方案意味着全量重建索引。我的实战经验：标题和正文分开建索引字段（title_en、title_zh 之类），查询时两个都查、权重合并。虽然 schema 啰嗦一点，但以后调优时你会感谢这个决定——中英文的相关性算法本来就不该用同一套参数。

上线检查清单

搜索功能上线前，对着这张清单过一遍。每一项都是真实项目里踩过的坑：

• 索引覆盖：所有该被搜到的内容类型都进了索引吗？（文章、正文、标题、标签——漏掉标签是最常见的）
• 增量更新：新建/编辑/删除内容后，索引实时更新吗？删掉的内容还能被搜出来是最尴尬的 bug。
• 中文验证：用 10 个真实中文词实测，确认分词正确。特别是 2-3 字的短词和专有名词。
• 空查询：搜索框空着点回车会怎样？应该是不查或返回推荐，而不是全表扫描把数据库打挂。
• 特殊字符：输入 &、|、!、引号会不会报错？plainto_tsquery 能防大部分，但前端也要做长度截断（比如 50 字符）。
• 性能基线：数据量 x10 之后还快吗？Postgres 方案确认 GIN 索引命中了 EXPLAIN；Typesense 方案确认内存够用。
• 权限：未发布/草稿内容会不会被搜出来？搜索 API 必须复用同一套可见性过滤，搜索不能成为越权查看的后门。
• key 隔离：用了 Typesense/Meilisearch 的话，前端 key 是只读最小权限吗？admin key 只在服务端出现。
• 零结果兜底：模糊查询和「是不是要找」提示接好了吗？空状态有推荐内容吗？
• 日志：搜索词开始记录了吗？第一周的数据会告诉你用户到底在找什么。

上线后看哪三个数

清单过完，功能上线，但工作没结束。搜索是个需要持续调的东西，上线后每周看三个数就够了：零结果率（搜了但没结果的比例，超过 15% 说明索引覆盖或分词有问题）、首结果点击率（用户点了第一个结果的比例，低说明排序不行）、搜索后转化（搜完之后用户有没有继续用产品，这是搜索的终极 KPI）。这三个数分别对应索引层、排序、业务价值，正好是开篇三层心智模型的镜像。数据难看别慌，一人项目的优势就是改得快：调个权重、补个同义词，当天就能上线验证。

最后说一句：搜索是那种「做出来之前觉得可有可无，做出来之后觉得早该做」的功能。它不性感，没有 demo 效应，但它是内容型产品从「玩具」到「工具」的分水岭。你的内容值得被找到——先让搜索框配得上它们。

如果你这周只能做一件事：先给 Postgres 加上 tsvector 和 GIN 索引，半天时间，让用户能搜到东西。下周再考虑 Typesense 的拼写纠错和即时联想。搜索体验是迭代出来的，不是一次设计出来的——但第一步，必须是让搜索框真实存在。