Shopify Storefront API
Storefront API 有两类令牌：公钥令牌可以放在浏览器，私有令牌只能留在服务端，搞混就会报 403 或直接暴露权限。本分类覆盖令牌放置、Cart API 的 cartCreate / cartLinesAdd 调用、变体 GID 写法，以及 Hydrogen 里取数失败的排查路径。
-
01
cartCreate 加 deliveryGroups 报字段不存在
按直觉拼 cartCreate(input: { lines: [...], deliveryGroups: [..……
-
02
cartLinesUpdate 把数量改成 0 行项目没删掉怎么办
购物车减到 0 时调用 cartLinesUpdate(lines: [{ id, quantity: 0 }])……
-
03
cart.cost.totalAmount 和结账金额对不上怎么核
购物车页显示 totalAmount 为 59.00 USD……
-
04
checkoutCreate 已停用后结账流程怎么改
老代码还在调 checkoutCreate……
-
05
checkoutUrl 跳到 myshopify 域名怎么换主域
站点跑在 www.example.com……
-
06
折扣码 applicable 为 false 却没减钱怎么查
cartDiscountCodesUpdate 返回 200、userErrors 为空……
-
07
Shopify Hydrogen cartCreate 失败怎么办
Hydrogen/cartCreate mutation 返回错误或 cart 为空，加购按钮无响应。
-
08
Hydrogen 的 storefront.query 总是返回旧数据
后台把商品标题改成新文案，Hydrogen 的 PDP 刷新十几次仍是旧标题；重启 dev server 会恢复……
-
09
image.transform 裁切方向总是不对怎么调
传 transform: { maxWidth: 400, maxHeight: 800, crop: LEFT }……
-
10
@inContext 传国家和语言怎么写才生效
写成 query($country: CountryCode) @inContext(country: $count……
-
11
metafields 带 namespace 报未知参数怎么取
照 Admin API 的写法写 metafields(namespace: "custom", first: 10……
-
12
Next.js action 调 Storefront 库存没更新
在 'use server' 的 action 里查 quantityAvailable，页面一直显示 10 件……
-
13
加了 @inContext(language) 商品标题还是原文
查询已经写了 @inContext(country: DE, language: DE)，价格变成 EUR 了……
-
14
products 传 first: 250 却拿不到全部商品怎么办
列表页只出现 250 个商品，后台明明有 800 多个……
-
15
Storefront API 返回 430 限流怎么处理
前端请求购物车或商品列表时，接口开始返回 430，页面出现空白或价格加载不出来。
-
16
Storefront API 的 availableForSale 与实际库存不符
商品实际有货，API 返回 availableForSale: false，前台显示售罄。
-
17
Storefront API 设置 buyerIdentity 后价格没变
给 cart 设置 buyerIdentity.countryCode 为 US……
-
18
Storefront API 购物车属性写不进订单怎么办
用 cartAttributesUpdate 写了备注与自定义字段，结账后订单里看不到。
-
19
Shopify cartLinesAdd 变体 GID 怎么写
cartLinesAdd 报变体不存在或 GID 无效。
-
20
Storefront API 拿到的 checkoutUrl 还能改吗
cart.checkoutUrl 已经生成，想在跳转前追加折扣码或备注，不确定能不能改参数。
-
21
Storefront API 的 errors 和 userErrors 怎么区分处理
加购失败时前端没有任何提示，只在控制台看到返回里有 errors 或 userErrors。
-
22
Storefront API 多市场多语言怎么正确传上下文
同一个商品在不同市场显示的价格与文案一样，切换语言也没生效。
-
23
Storefront API 拿不到 metafield 是权限问题吗
后台商品已经填了 metafield，Storefront API 查询返回 null，Admin API 查却有值。
-
24
Storefront API 搜索建议返回空怎么排查
调用 predictiveSearch 传关键词返回空数组，前台搜索框没有任何联想。
-
25
Storefront API 私有令牌用在浏览器会失败
把 Storefront 私有令牌写进前端后，部分查询偶发成功（若服务器代发），但浏览器直连被拒……
-
26
Shopify Storefront API 公钥令牌放错位置
无头或 Hydrogen 店面在浏览器控制台出现 Storefront API 401/403，或服务器渲染能通……
-
27
Storefront API 多个查询能不能合并成一次请求
首页需要轮播、热销、新品三组数据，发了三个请求，首屏等待时间叠加。
-
28
Storefront API token 需要哪些权限才够用
新建的 Headless 渠道 token 查询商品正常，但读不到库存或 metafield，报未授权。
-
29
Storefront API 商品变体超过 250 个怎么取全
查询 variants(first: 250) 只拿到 250 个，商品实际有 600 个变体。
-
30
Storefront API 和 Ajax API 该用哪个
主题要做一个加购交互，不知道该调 /cart/add.js 还是 Storefront GraphQL。
-
31
Storefront API 购物车 ID 失效怎么办
用户昨天加的购物车今天打开提示购物车不存在，或换设备后购物车为空。
-
32
Storefront 查询前面加 CDN 后购物车数量不更新
给 GraphQL 端点套了一层 CDN，商品页确实变快，但加购后角标一直显示 1，换个浏览器又是对的……
-
33
Storefront API 多语言上下文币种不对怎么处理
站点切到某个市场后，接口返回的价格仍是本币；或者语言变了，商品标题还是默认语言。
-
34
浏览器请求 Storefront API 报 CORS 被拦截怎么查
本地 fetch 时控制台报 blocked by CORS policy: No 'Access-Control-……
-
35
把 Admin 的限流算法套到 Storefront 上会误判
监控里 extensions.cost.throttleStatus.currentlyAvailable 看着很充……
-
36
Storefront API 图片转换参数不生效怎么办
请求里带了 transform: { maxWidth: 800 }，返回的图片仍是原图尺寸，移动端加载很慢。
-
37
Storefront 搜索传 query 却搜不到商品怎么写
前端把用户输入直接塞进 products(query: "红色 连衣裙")，结果为空；换成单个英文单词能搜到……
-
38
Storefront API 两个令牌头写反了返回 401 怎么区分
服务端日志里请求带的是 Authorization: Bearer xxx 或 X-Shopify-Access-T……
-
39
Storefront 令牌轮换后老前端全部 401 怎么过渡
后台把 Headless 渠道的 public token 轮换后……
-
40
Shopify 后台在哪里创建 Storefront API 令牌
在后台 Settings 里翻遍 Apps and sales channels……
