Storefront API 搜索建议返回空怎么排查

现象#

调用 predictiveSearch 传关键词返回空数组，前台搜索框没有任何联想。

原因#

• 关键词包含中文而店铺搜索索引按英文分词
• 传参用了 query 但字段名实际是 query 与 limit，类型不符
• 商品未发布到 Storefront 渠道
• 搜索被 types 过滤条件限制

处理步骤#

1. 先用最简单的 predictiveSearch(query: "shirt", limit: 5) 验证通路
2. 确认商品已发布到「在线商店」销售渠道
3. 中文店铺改用 products(query:) 并配合拼音/英文关键词映射
4. 检查返回的 available 与 publishedAt

验收标准#

关键词能返回相关商品与集合建议，点击后跳转正确，中文场景有可用替代方案。