Storefront API 拿不到 metafield 是权限问题吗

现象#

后台商品已经填了 metafield，Storefront API 查询返回 null，Admin API 查却有值。

原因#

• metafield definition 的 access.storefront 为 NONE
• 查询时没有指定 namespace 与 key
• metafield 属于未发布的 definition

处理步骤#

1. 在后台「自定义数据 → 定义」里把 Storefront 访问权限改为 PUBLIC_READ
2. 查询写全：metafield(namespace: "custom", key: "badge") { value type }
3. 列表字段用 metafields(identifiers: [...]) 批量取
4. 改完权限后重新查询，必要时清 CDN 缓存

验收标准#

Storefront API 能读到与后台一致的 metafield 值，类型正确，前端渲染正常。