用途:本技能讲解 Saleor storefront 中结账会话如何创建、存储和管理,用于排查结账问题、支付失败、水合不匹配等故障。
结账 ID 存储:存于两处。Cookie(主要存储)名为 checkoutId-{channel},如 checkoutId-default-channel,在 src/lib/checkout.ts 中通过 saveIdToCookie 设置,sameSite 为 lax,secure 由 shouldUseHttps 决定。另一处为 URL 查询参数,如 /checkout?checkout=Q2hlY2tvdXQ6...,该 ID 是 base64 编码的 Saleor 全局 ID。
生命周期:当用户向空购物车添加首个商品、Cookie 中无有效结账 ID、或 Saleor 中找不到已有结账时创建新结账(findOrCreate)。结账可跨页面刷新、浏览器会话(基于 Cookie)和购物车修改持久存在。checkoutComplete 变更成功后,结账转为订单,原结账 ID 失效,后续购买应新建结账。
常见问题:一、水合不匹配,SSR 阶段调用 extractCheckoutIdFromUrl() 读到空 URL,导致 React 水合不匹配和 PageNotFound 闪现,修复方式是延迟到客户端挂载后再提取,可参考 src/checkout/hooks/useCheckout.ts。二、失败交易导致结账陈旧,多次支付失败会累积部分交易,后续尝试可能报 CHECKOUT_NOT_FULLY_PAID;可清除 checkoutId-{channel} Cookie、用无痕窗口或去掉 URL 参数。三、金额不匹配,交易初始化后结账总额变化(如新增运费),支付前应使用 useCheckout() 的实时数据。
关键文件:src/lib/checkout.ts(创建与 Cookie 管理)、src/checkout/hooks/useCheckout.ts(React Hook)、src/checkout/lib/utils/url.ts(URL 参数提取)、src/graphql/CheckoutCreate.graphql(创建变更)。
调试:可在浏览器控制台查看 Cookie,用 atob 解码 URL 中的结账 ID,或在 GraphQL playground 查询结账的 totalPrice 与 transactions。
支付应用问题:报 AUTHORIZATION_FAILURE 通常是支付应用未响应,可检查 Saleor Dashboard 中应用是否激活、支付应用 URL 是否可达、自托管时重启应用、云托管时查看 Saleor Cloud 状态。CHECKOUT_NOT_FULLY_PAID 的成因包括支付应用宕机、陈旧结账、金额不匹配,可查看交易初始化日志中的 transactionEvent.type 判断。
最佳实践:支付金额始终使用实时结账数据;优雅处理找不到结账并新建;完成后清理结账避免陈旧数据;调试支付问题时用全新结账测试;交易以 AUTHORIZATION_FAILURE 失败时检查支付应用健康状态。官方文档与收费信息暂未提供。