metafield 的 namespace 和 key 写错就读不到值

现象#

后台明明存着 Custom.Material，Liquid 里写 product.metafields.custom.material 却输出空，换成方括号写法也一样。

原因#

• namespace 与 key 区分大小写，Custom 和 custom 是两个不同的键
• namespace 至少 3 个字符、key 至少 2 个字符，只能用字母数字下划线和连字符
• 点号只是查询语法，真实字段是两段独立字符串，不能把整串当 key 传
• Liquid 里 key 与过滤器同名时（size、first）会被当成过滤器调用

处理步骤#

1. 到 Settings > Custom data > Products 复制现成的 namespace 与 key，不要手打
2. Liquid 统一写 product.metafields['custom']['material'].value 避开同名过滤器
3. GraphQL 用 metafield(namespace: "custom", key: "material") 两段分开传
4. 排查时遍历 product.metafields.custom 打印全部 key，确认拼写
5. 应用写入的数据放 $app: 前缀命名空间，别和商家自定义混在一起

验收标准#

同一商品在 Liquid、GraphQL、Storefront API 三处取到的值完全一致，且不再出现空字符串。