Shopify 知识库 · 概念
自定义数据：Metafield、Metaobject 与动态来源
说明 Shopify 自定义数据的两种载体 metafield 与 metaobject，定义与条目、命名空间、标准类别 metafield、动态来源，以及在 Liquid 与 API 中的读取入口和官方给出的数值上限。
Shopify 自定义数据（Custom data）让商家和应用在标准数据模型之外保存自己的结构化信息，并把它们展示到主题、传给 API 或交给 Functions 使用。它有两种载体：给现有资源加字段的 metafield，和自己定义记录类型的 metaobject。它解决的是「结构化事实存在哪里、怎么被页面复用」；它不决定页面怎么呈现，也不保证任何主题会自动渲染某个字段。
本库哪些内容依赖它
本文是 Shopify 自定义数据机制的权威来源，其他文章只写各自页面语境下的用法：
- 内容类型：商品规格（单位型参数与类别 metafield）、FAQ（用元字段承载商品级问答）、包装清单（列表类型与变体级承载）、商品概述（结构化补充）、顾客评价（标准评价 metaobject 与
reviews.rating）。 - 模块：尺码与适配指引（Page 引用 metafield 加动态来源）、评价展示、集合浏览与筛选（metafield 作为筛选来源，见Search & Discovery）。
- 页面与主题：尺码敏感商品页、主题内容架构与模板（
metaobject/{type}模板）、商品与变体。
核心对象与概念
| 对象 | 含义 | 备注 |
|---|---|---|
| Metafield | 现有资源上的额外字段，如保养说明、会员等级 | 可用于商品、变体、集合、客户、订单等，Storefront API 另列文章、博客、购物车、公司、销售计划 |
| Metafield definition | 声明 name、namespace、key、type、验证与访问权限 | 创建后 type、namespace/key、owner type 不可改；name、description、validations、access 可改。有定义才有类型化编辑器与写入验证 |
| 未定义的 metafield | 只作为纯文本字符串保存 | 商家无法对它做搜索或验证（shopify.dev Custom data） |
| namespace 与 key | 形如 custom.warranty_info | $app（GraphQL）或 app（TOML）是应用专属保留命名空间；shopify-- 前缀由 Shopify 保留 |
| Metaobject definition | 一种记录类型的模式：type、字段、验证、访问权限、可选能力、显示名 | 后台在 Settings > Custom data 管理；type 由名称自动生成，保存前可改 |
| Metaobject entry | 定义的一个实例，如一位作者、一组问答 | 后台在 Content > Metaobjects；可被 metafield 引用，也可独立使用 |
| Display name | 指定一个字段用来标识条目 | 默认取第一个文本字段，无文本字段时自动生成，可随时改 |
| Metaobject 能力 | publishable：DRAFT / ACTIVE，新建默认 DRAFT；translatable：字段翻译；renderable：向 Liquid 与 Storefront API 暴露 SEO 字段并进入 sitemap；onlineStore：分配模板与 URL | onlineStore 需要 URL handle，页面地址形如 /pages/{urlHandle}/{entry-handle}；官方页写明该能力目前不能用 TOML 配置 |
| 类别 metafield（Category metafields） | 与商品类别绑定的属性，带默认条目，如衬衫的尺码、领型、袖长 | 每个商品只有一个类别，来自 Standard Product Taxonomy；值用 metaobject 条目表示，可改名（如把 black 改成 graphite），可关联变体选项 |
| 动态来源（Dynamic sources） | 让主题编辑器里的区段与区块设置连接到资源、metafield 或 metaobject 数据 | 需要主题支持；旧主题需改主题代码 |
| 访问控制 | Admin：merchant_read（默认）/ merchant_read_write；Storefront API：none（默认）/ public_read；Customer Accounts API：none / read / read_write | 见 shopify.dev Metafields 页，适用于应用声明的定义；商家自有的 metaobject 对商家与授权应用自动开放读写 |
Metafield 与 metaobject 的分工：数据描述一个已有资源就用 metafield；数据本身是独立记录（尺码表、门店、成分）就用 metaobject，并用 metafield 把它挂到商品上。这一区分来自 shopify.dev Custom data 页。
在哪里配置
- 定义：帮助中心的 Metafields 定义页给出 Metafields 页面入口
admin.shopify.com/metafields，可添加 Standard definitions（各店通用模板）或 Custom definitions；使用教程写 Settings > Metafields and metaobjects > Product metafields > Add definition；Metaobjects 页写 Settings > Custom data。两个菜单名都出现在官方页面，当前 Admin 实际显示名未核验。 - 填值：Products > 选择商品 > Product metafields 区域；类别属性在商品的 Category 区域，Category metafields 单独成段。
- 条目：Content > Metaobjects。
- 主题连接：Online Store 主题编辑器，在支持动态来源的设置旁点击 Connect dynamic source 图标。教程示例是在商品模板的 Product information 里添加 Collapsible row，再连接 metafield。
- 权限：官方页写明员工需要对应资源的 View、create and edit 权限才能管理 metafield。
- 只读的例外：
reviews.rating等应用维护的标准 metafield 不在后台显示，见顾客评价。
与主题、Liquid 和 API 的连接
- Liquid 读取 metafield：
{{ resource.metafields.namespace.key }}；key 名为size、first、last时用方括号写法。metafield 对象有list?、type、value；文本返回字符串，reference 返回对应对象，weight、volume、dimension返回度量对象，日期类返回字符串。列表的value是数组，长度对引用类型用count，其他类型用size过滤器。Liquid 不能创建 metafield。店铺级用shop.metafields。 - Liquid 读取 metaobject：顶层
metaobjects.type.handle（旧的shop.metaobjects已弃用）；基本信息放在system下避免与自定义字段重名；启用 publishable 后只有active状态可读，草稿返回nil。metaobject 模板内当前条目是metaobject，字段用metaobject.title.value。 - Storefront API：实现
HasMetafields的资源提供metafield(namespace, key)与带分页的metafields；value恒为字符串，靠type解释，引用类型用reference/references取对象；所有字段都需要令牌访问。定义上access.storefront为public_read时对顾客可见，none时隐藏。cartMetafieldsSet一次最多 25 个，存在匹配定义时会复制到订单。 - Admin API：商家自有定义只能用 GraphQL Admin API 创建，不能用 TOML；应用自有定义用
shopify.app.toml。metafieldsSet每次 25 个、metafieldsDelete每次 250 个。 - Functions 与扩展：官方写明 Shopify Functions 输入查询、checkout 与 admin 扩展都能读取自定义数据。
- 动态来源支持的设置类型：article、collection、collection_list、color、image_picker、page、product、product_list、richtext、inline_richtext、text、url、video、metaobject、metaobject_list。
限制、数值与易错点
核验于 2026-09-29。官方页面之间的差异并列，不选边。
| 项目 | 官方所写 | 来源 |
|---|---|---|
| metafield 定义数量 | 每店最多 250 个 | 帮助中心 Metafield definitions |
| 同上 | 应用与商家各自每种资源类型最多 256 个；置顶定义每种资源类型 50 个 | shopify.dev Metafield 限制页 |
| 同上 | 每个 owner type 每个应用 128 个；单次部署最多 25 项变更 | shopify.dev Metafield definitions 页 |
| 值大小 | 一般类型 64KB；id、url 2KB；json 128KB；单行文本预设选项 128 个 | Metafield 限制页 |
| 列表 | 最多 128 项，metaobject 引用列表 1024 项 | Metafield 限制页 |
| 数字范围 | number_integer ±9,007,199,254,740,991；number_decimal ±9999999999999.999999999 | 数据类型页 |
| 无 list 版本的类型 | boolean、id、json、language、money、multi_line_text_field、rich_text_field | 数据类型页 |
| 能力上限 | 智能集合条件 128；Admin 筛选 50（订单 5） | Metafield 限制页 |
| metaobject 定义数量 | Basic、Shopify、Advanced 各 128；Plus、Enterprise 各 256；应用 128 | Metaobject 限制页 |
| metaobject 结构 | 每个定义最多 40 个字段、1,000,000 个条目 | Metaobject 限制页 |
| 动态来源数量 | JSON 模板、通用主题设置、区段组各最多 100；单个设置、静态区段各最多 50 | Dynamic sources 页 |
- 同页内部矛盾：Dynamic sources 页在限制中列出「通用主题设置 100」，同页又写动态来源不适用于通用主题设置；本文两句并列，不解释原因。
- 定义是否必须先于值：shopify.dev Metafields 页写定义必须先于值创建；帮助中心 Metafields 页与 Custom data 页承认存在未定义的 metafield（纯文本）。两者语境（应用创建 vs 商家既有数据）可能不同，未核实。
- 类别属性：商品分类页写明目前不支持自定义类别属性；未分类商品保存为 uncategorized。
- 类型限制在下游：Search & Discovery 的 metafield 筛选只支持部分类型，见Search & Discovery。
- POS：官方写明 POS 只显示置顶的客户 metafield，以及置顶与未置顶的商品 metafield。
- 搜索可见性：
seo.hidden是一个约定命名的整数 metafield（值 1 隐藏），Unlisted 状态优先，详见搜索页面。
验证一次
- 在测试店铺创建一个带验证的 metafield 定义（如
custom.care_guide），另建一个商品只填值、一个商品留空。 - 在商品模板连接动态来源，确认有值商品显示、无值商品不留空壳。
- 用
{{ product.metafields.custom.care_guide.value }}与.type输出，核对类型与 list 行为。 - 创建 metaobject 定义与两条条目，一条设为 DRAFT，用 Liquid 读取，确认草稿为
nil。 - 用 Storefront API 分别在
access.storefront为public_read与none下取同一 metafield，记录差异。 - 换语言与市场重复，确认翻译与显示。
待继续完善
- 未在真实店铺核对 Settings 下的菜单实际名称与各类型的编辑器表现。
- 250、256、128 三个定义上限的适用差别未核实。
- Metaobject 条目在多语言与 Markets 下的翻译行为、类别 metafield 的完整清单未核验。
- 主题自动渲染 metafield 的范围因主题而异，未逐主题核对。