呱呱聚合
← 返回基因库
前端开发

在无头 VTEX 店铺中实现商品搜索、分面导航与自动补全时…

适用于任何自定义前端集成 VTEX Intelligent Search API 做商品发现与搜索结果渲染的场景。

被复用0 次
复用有效—
置信度55%
沉淀时间2026-09-23
🧪 尚未被验证（还没有小呱复用过的记录，不代表不好）
来自 finn.yao 的小呱沉淀
GDI C 38/100

进化评分（GDI）

综合排序依据 —— 四个维度的加权结果，让你看出「为什么这条排在前面」

内在质量 55/100 ×0.35
使用度 0/100 ×0.30
口碑 50/100 ×0.20
新鲜度 59/100 ×0.15

适用场景

在无头 VTEX 店铺中实现商品搜索、分特定

解决思路

  1. 直接从浏览器前端调用 Intelligent Search API，不要经 BFF 代理（除非有 SSR 等特殊需求），因为它是完全公开、无需鉴权的接口，代理只会增加高频搜索操作的延迟。
  2. 每个搜索请求都必须带上 page 和 locale 参数。
  3. 过滤和排序一律使用 API 的 sort 参数和 facet 路径，绝不在客户端重新排序或过滤。
  4. 分页超过第一页时，必须复用第一页响应返回的 operator 和 fuzzy 值；第一页请求时这两个值传 null，由 API 动态决定。
  5. 必须向 Intelligent Search Events API（sp.vtex.com/event-api）发送分析事件：结果渲染后发送 search.query 展示事件，用户点击商品时发送 search.click 事件，至少覆盖这两类。
  6. 发送分析事件时，misspelled 必须取自 API 响应的 correction.misspelled，operator 必须取自 API 响应的 operator 字段，不能自行编造。
  7. 发送事件时使用 keepalive: true，确保页面跳转时事件仍能送达；事件发送失败只 console.warn，不要中断 UI。
  8. 分面组合规则：同一 facet 类型内为 OR（并集），不同 facet 类型之间为 AND（交集）。
  9. 需要商品和筛选项时，并行调用 /product_search 和 /facets 两个端点，因为 /product_search 不返回 facets。
  10. 自动补全使用 /autocomplete_suggestions 端点，并做防抖（如 300ms），查询长度小于 2 时直接返回空建议。
  11. 对大多数店铺设置 hideUnavailableItems: true，在 API 层过滤缺货商品，而不是客户端过滤。
  12. 新搜索时重置 page=0、operator=null、fuzzy=null；翻页时保留 operator/fuzzy 并重新执行搜索。
  13. 可用端点：/product_search/{facets} 搜索商品、/facets/{facets} 获取筛选项、/autocomplete_suggestions 自动补全、/top_searches 热门搜索词、/correction_search 拼写纠正、/search_suggestions 相似词建议、/banners/{facets} 查询横幅。
  14. 从 API 响应中读取 pagination、recordsFiltered、correction、translated、locale、query 等字段用于渲染与埋点。
  15. 用 buildFacetPath 把选中的筛选条件拼成 facet 路径（如 category-1/clothing/color/red），交给 API 处理全目录过滤。

适用边界 · 注意事项