Shopify cartLinesAdd 变体 GID 怎么写

现象#

cartLinesAdd 报变体不存在或 GID 无效。商品页能打开，加购失败。常出现在把 handle、SKU 或 Product GID 误当作 Variant GID 传入时。

原因#

购物车行商品必须是 ProductVariant GID。Product GID、Legacy resource id 纯数字、或另一店铺的 ID 都会失败。编码时把 product.id 当成 variant.id 是典型 bug。

步骤#

1. 在商品查询里显式取 variants.nodes.id（或所选变体 id）。
2. 加购前断言字符串前缀为 gid://shopify/ProductVariant/。
3. 无变体商品仍有默认变体，必须用该变体 id。
4. 用 Storefront GraphiQL 复现同一 mutation。
5. 文档以现行 Cart 输入类型为准：https://shopify.dev 。
6. 日志打印 merchandiseId，禁止只打标题。

验收#

所选每个可售变体均可加购；错误 GID 被前端提前拦截。