商品 metafield 在主题里输出为空怎么排查

现象#

后台商品页已经填了自定义字段，主题里 {{ product.metafields.custom.xxx }} 却是空白。

原因#

• metafield 定义未开启 Storefront 访问权限
• namespace / key 拼写不一致，或用了中文名当 key
• 字段类型是列表或富文本，需要按对应结构遍历，不能直接输出
• 值填在变体层级，商品层级本身为空

处理步骤#

1. 在 设置 → 自定义数据 里确认该定义对 Storefront 可见
2. 用 {{ product.metafields.custom | json }} 打印全部字段，核对真实 key
3. 列表类型用 for 遍历，富文本用 | metafield_tag 输出
4. 确认数据挂在商品还是变体上，变体级用 variant.metafields

验收标准#

前台正确显示字段内容；空值时走 default 兜底不报错。