Headless Commerce 缓存与预览上线前 QA 检查清单

Headless Commerce 通常至少有三个容易不同步的地方：电商平台、CMS 和前端缓存。一个页面在测试时可能加载很快，但仍然显示昨天的价格、旧商品图、缺失的翻译，或者活动更新后没有刷新的 SEO 元数据。

这份清单适合 Shopify Headless、组合式电商、Next.js 店铺、CMS 驱动的商品故事页，以及依赖静态生成、边缘缓存、API 缓存或按需重新验证的网站改版。上线前、大促前，以及内容模型或缓存规则变化后都应该跑一遍。

不要一开始只刷新一个商品页。先列出所有可能被缓存的页面，以及每个页面背后的来源系统。商品详情页、集合页、搜索结果、导航、页脚链接、推荐模块、内容区块、图片转换、SEO 元数据、结构化数据、XML 站点地图、Feed 和多语言路由，都可能有不同的刷新规则。

这份清单应该写清楚来源系统、前端路由、缓存类型、预期更新时间和负责人。没有这张表，上线 QA 很容易变成随机刷新页面。

• 电商数据：标题、handle、价格、划线价、库存、可售状态、变体、选项、图片、集合、标签、metafield 和订阅计划。
• CMS 数据：落地页、购买指南、内容模块、横幅、FAQ、站点设置、翻译、导航和可复用证明区块。
• SEO 数据：title、meta description、canonical、hreflang、schema、Open Graph 图片、robots 规则和站点地图。
• 基础设施：静态生成、边缘缓存、API 缓存、图片缓存、CDN 规则、预览 cookie、Webhook 处理器、队列和手动清缓存工具。

不是所有路由都需要同样的缓存行为。首页活动横幅可能需要一分钟内更新，尺码指南可以等更久。商品价格和可售状态通常要比编辑内容更严格。关键是先说清业务预期，再让开发决定 cache header 或重新验证间隔。

做一张小表，字段包括页面类型、触发来源、预期新鲜度、兜底行为、清缓存方法和上线负责人。尽量用具体数字，不要写模糊词。比如商品价格两分钟内更新，比商品页应该保持新鲜更容易测试。

• 把高收入页面和低风险的常青内容分开标记。
• 分别定义商品页、集合页、购物车相邻页面、活动页、博客、资源页、政策页和多语言页面的规则。
• 写清楚 API 出错时应该怎么办：继续展示旧内容、隐藏模块、显示兜底数据，还是阻止发布。
• 确认预览是否绕过缓存、使用草稿数据，或者只预览 CMS 内容而电商数据仍然来自线上。

预览模式不能只用完美样例页测试。编辑团队需要预览未发布页面、定时模块、翻译文案、很长的商品名、不可售商品、草稿 SEO 字段，以及引用电商数据的内容模块。

一次有价值的预览测试要回答两个问题。第一，编辑看到的草稿状态是否正确。第二，预览状态和线上店铺是否足够清楚地分开，避免有人把草稿当成已发布内容。

• 预览新落地页、被编辑过的商品故事、隐藏模块、定时促销和多语言页面。
• 确认预览 cookie、鉴权、草稿 API 和 noindex 规则不会泄露到公开页面。
• 测试长标题、缺失图片、空的可选字段、未发布引用和缺货商品。
• 给编辑团队一个统一的预览 URL 规则，并说明什么时候需要重新生成或分享。

Webhook 是很多 Headless 上线不稳定的地方。商品更新可能来自 Shopify，内容更新可能来自 CMS，集合变化可能同时需要刷新路由页和列表页。如果处理器只刷新最明显的页面，相关页面就会继续过期。

做一张测试表，每一行只改一个字段，并列出所有应该刷新的路由。然后在来源系统里真实修改，再检查线上店铺、渲染后的 HTML、API 响应，以及需要时的站点地图。

• 商品测试：价格、促销价、库存、变体标题、商品图、metafield、SEO 标题、handle 和集合归属。
• 集合测试：排序、筛选值、集合说明、头图、分页和商品可售状态。
• CMS 测试：活动模块、首页区块、资源页、导航项、页脚链接、可复用推荐语和多语言内容。
• 路由测试：PDP、集合卡片、搜索结果、推荐模块、站点地图 URL、schema 输出和 Open Graph 元数据。

最难发现的问题通常出现在多个更新靠得很近的时候。运营先改价格，再改库存，再改集合归属。内容编辑在商品数据还没同步完时发布活动。中文翻译在英文页面已经重新验证后才审批通过。

有意识地做几组竞态测试。在一分钟内发布两个相关变化，更新一个出现在多个页面的商品，取消发布一个被引用的 CMS 条目，或者修改商品 handle。观察店铺最后是否一致，还是混合了新旧数据。

• 确认来源变化影响多个路由时，相关页面会一起刷新。
• 检查队列是否会重试失败的 Webhook 任务，以及失败是否对团队可见。
• 测试单个 URL、路由模式、商品相关页面和全站的手动清缓存。
• 确认删除或取消发布内容后，链接、卡片、schema 引用和站点地图条目都会移除。

页面正文刷新了，不代表 SEO 输出也刷新了。对 Headless 网站来说，这是很真实的上线风险，因为元数据、结构化数据、站点地图、图片 URL 和 canonical 可能由应用里的另一层逻辑生成。

每次重要的重新验证测试后，都要检查渲染后的 HTML 和 API 输出。重点看最终 title、meta description、canonical、hreflang、商品 schema、可售状态、价格、Open Graph 图片、robots 指令和站点地图收录。

• 确认结构化数据里的促销价和可售状态与页面可见内容一致。
• 检查 handle 变化后是正确重定向或 canonical，而不是生成重复 URL。
• 翻译更新后验证多语言元数据和 hreflang。
• 缓存清理后重新抓取一组样本 URL，避免只发现页面 UI 过期，而漏掉元数据过期。

不要等到上线当天才决定谁能清缓存，或者坏内容发布后怎么回滚。Headless Commerce 需要运营预案，因为过期内容会影响收入、SEO、客服工单和活动信任度。

上线前，写清楚手动清缓存路径、回滚路径、Webhook 日志、失败任务提醒、可用性检查、错误看板和升级负责人。团队要能快速回答一个简单问题：是来源内容错了、Webhook 延迟了，还是缓存还在展示旧输出。

• 监控 404、API 错误、重新验证失败、Webhook 重试、库存过期反馈和高价值商品页。
• 准备首日手动检查的关键收入 URL 列表。
• 指定电商数据、CMS 内容、前端部署、SEO 检查和清缓存权限的负责人。
• 为价格过期、库存错误、预览失效和活动更新失败写一页事故处理流程。