从 Storefront API 版本 2027-01 开始，Market.metafields 在匹配键时不区分大小写。

截至 Storefront API 版本 2027-01，Market 对象上的 metafields 字段以不区分大小写的方式匹配任何请求的键，这与 Market.metafield 的行为一致。对于以与存储键不同的大小写请求市场元数据字段的键，或读取买家市场存储的因字母大小写而异的键的应用程序和自定义商店而言，这是一个破坏性更改。如果您的应用程序执行其中任一操作，请在将其迁移到 2027-01 之前审查其 Market.metafields 查询。

变更内容

在 2027-01 版本中，当请求的键以不区分大小写的方式匹配存储的键时，Market.metafields 返回一个元数据字段。在早期版本中，Market.metafields 仅在请求的键和存储的键具有相同大小写时才返回元数据字段。

例如，市场存储了一个命名空间为 custom、键为 colour 的元数据字段：

• 在 2026-10 及更早版本中，{ namespace: "custom", key: "Colour" } 的条目为 null。
• 在 2027-01 版本中，该条目返回存储的元数据字段。

受影响对象

此更改适用于从 Localization.market 或 Country.market 对 Market 对象查询 metafields 的应用程序和自定义商店，且使用 Storefront API 版本 2027-01 或更高版本。仅当满足以下任一条件时，您的应用程序才会受到影响：

• 它请求的键的大小写与市场存储的键不同。
• 买家的市场以不同的大小写存储相同的键。

如果您的应用程序以市场存储它的大小写请求每个键，或者仅使用已经以不区分大小写方式匹配键的 Market.metafield，则您的应用程序不受影响。2026-10 及更早版本不会发生变化。

为何重要

在早期版本中，Market.metafield 和 Market.metafields 对于相同的键可能返回不同的结果：Market.metafield 找到元数据字段，而 Market.metafields 返回 null。在 2027-01 中，两个字段都返回相同的元数据字段，因此无论您的商店查询哪个字段，都会显示相同的值。

该怎么做

Market.metafield 已经以不区分大小写的方式匹配键，并从买家最具体的市场中返回元数据字段。因此，在您今天使用的版本中，Market.metafield 返回的结果与 2027-01 中 Market.metafields 返回的结果相同。您可以比较这两个字段以确定此更改是否会影响您的应用程序。

1. 对于您的应用程序读取的每个市场元数据字段，请使用相同的命名空间和键查询 Market.metafield 和 Market.metafields，并比较结果。
2. 如果每个键的结果都相同，则无需进行更改。
3. 如果结果存在差异，请检查该差异是否对您的应用或 storefront 产生实质性影响。
4. 如果有影响，请更新您的应用和 metafields，使其不再依赖键的大小写。例如，按照您的市场存储的方式请求每个键，并在每个市场上对每个键使用统一的大小写。

query CompareMarketMetafields @inContext(country: CA) { localization { market { metafield(namespace: "custom", key: "Colour") { key value } metafields(identifiers: [{ namespace: "custom", key: "Colour" }]) { key value } } } }

相关文档

• Market Storefront API 中的 Market 对象
• Storefront API 2027-01 参考
• 使用 Storefront API 检索 metafields
• 关于 Shopify API 版本控制