Skip to Content
🎉 探索 Shopify 的无限可能 结构化知识 + 实战案例，持续更新中...
进阶教程Shopify 元字段与元对象

Shopify 元字段 (Metafields) 与 元对象 (Metaobjects) 深入指南

Shopify 管理员中的元字段与元对象定义

视频讲解

适用读者：主题开发、应用开发者、店铺运营需要结构化数据的团队

核心概念

  • Metafields：给某个具体对象加“小字段”。就像给产品贴便签：副标题、成分、保质期等。一个 namespace.key 对应一个字段值（可以是单值或 list.* 多值）
  • Metaobjects：自定义一类“内容类型”。像一个可复用的内容表（多字段、能建多条记录），例如“尺码表”“门店列表”“品牌故事”等

二者怎么配合：简单加一两个属性 → 用 Metafields；需要一套可复用的结构化内容 → 先建 Metaobject，再用 metaobject_reference 类型的 Metafield 去引用它

如何选择

  • 只想给某个资源加个小字段 → 用 Metafield
  • 需要一类可复用、可建多条记录的内容 → 用 Metaobject
  • 在产品/集合里引用复杂内容 → 在资源上建 Metafield（类型选 metaobject_reference）指向对应 Metaobject
  • 全站统一配置（如站点 Slogan） → 放到 shop.metafields
  • 每个变体都有不同值 → 放到 variant.metafields

为什么需要元字段？（精华）

  • 扩展数据模型：为产品/变体/集合/客户等添加默认字段之外的关键信息
  • 可视化接入：与 Online Store 2.0 主题“动态来源”对接，无需改代码即可展示
  • 结构化与校验：字段带类型与验证规则，保障录入一致、可被模板安全使用
  • 精细运营：用元字段做筛选、智能集合条件、列表展示与后台置顶，提高运营效率
  • 多语言与本地化：部分类型支持翻译，多语言站点展示更准确
  • 复用复杂内容：结合 metaobject_reference，引用“尺码表/品牌资料/门店信息”等可复用模块
  • SEO 与信息完整度：补充规格、材料、下载文件、摘要要点，提升页面信息质量
  • 渠道与场景：置顶的客户/产品元字段可在 POS 等场景快速查看

高频场景与示例

  • 产品补充信息：燃烧时长、配料/成分、食品保质期、护理与洗涤说明
  • 视觉呈现：颜色样本（色块）列表、下载文件（说明书/证书）
  • 关联增强：相关产品/文章、品牌故事、尺码表（用 metaobject + 引用）
  • 内容摘要：博客文章摘要、关键卖点要点清单（list.single_line_text_field）

元字段与元对象的使用示例图：

Shopify 的元字段与元对象使用示例

提示：简单字段直接用 metafield；需要多字段可复用模块（如“品牌资料”“门店信息”）优先用 metaobject，再由资源侧以引用连接

命名空间与键

  • 命名规范：namespace.key，如 custom.subtitle
  • 约定：使用团队统一的 namespace 前缀，避免冲突，例如 storefront_、marketing_

支持的类型（常用）

  • 文本类：single_line_text_field、multi_line_text_field、rich_text、url、json、color
  • 数值类：number_integer、number_decimal
  • 布尔类：boolean
  • 媒体类：file_reference、image_reference
  • 关系类：product_reference、variant_reference、collection_reference、metaobject_reference
  • 日期类：date、date_time

以上多数类型支持列表变体：list.*（例如 list.single_line_text_field、list.product_reference）

补充特性

  • 类别元字段（Category metafields）：与产品分类绑定，用于标准化属性（如颜色、尺码等），条目基于 metaobjects
  • 置顶（Pinning）：可在后台资源详情中将常用元字段置顶；Shopify POS 显示置顶的客户元字段，以及置顶与未置顶的产品元字段
  • 主题动态源：支持 Online Store 2.0 主题在可视化编辑器中将元字段连接为动态数据源

后台操作速查

  1. 新建元字段定义：管理后台 → 设置 → 自定义数据 → 选择资源（产品/变体/集合等）→ 添加定义（设定名称、namespace.key、类型与验证）
  2. 填写字段值：到对应资源详情页，找到“自定义数据/元字段”区域录入（支持置顶常用字段）
  3. 连接到主题：在线商店 → 主题 → 自定义，在区块/组件里选“动态来源”绑定元字段值
  4. 新建元对象定义：设置 → 自定义数据 → 元对象 → 添加定义（配置多字段）并创建条目（Entry）
  5. 在资源引用元对象：为资源添加 metaobject_reference 类型的元字段，并选择具体条目
  6. 在主题展示：同第 3 步，通过动态来源绑定或在代码中读取引用内容

批量与运营提示

  • 批量编辑：产品列表 → 选择多项 → 批量编辑 → 添加列选择相关元字段后统一修改
  • 智能集合：可用元字段作为条件组合，构建更精细的商品集合
  • POS/后台可见性：将关键字段“置顶”，便于收银与运营快速查看

在主题（Liquid）中读取 Metafields

<!-- 读取产品自定义副标题 custom.subtitle -->
{% if product.metafields.custom.subtitle %}
  <p class="text-gray-600 text-sm">{{ product.metafields.custom.subtitle | escape }}</p>
{% endif %}
 
<!-- 读取 JSON 类型并解析 -->
{% assign spec = product.metafields.custom.spec_json | default: '{}' %}
{% assign spec_parsed = spec | json %}

在主题中读取 Metaobjects

<!-- 假设 metafield 保存了 metaobject 引用：custom.size_chart -->
{% assign size_chart = product.metafields.custom.size_chart %}
{% if size_chart %}
  <div class="space-y-2">
    <h3 class="text-lg font-medium">{{ size_chart.title }}</h3>
    <div class="prose max-w-none">{{ size_chart.content }}</div>
  </div>
{% endif %}

说明：metaobject_reference 类型会返回该对象的已发布字段，可直接在主题中访问

Admin GraphQL：创建/更新 Metafields 示例

mutation UpsertProductMetafield($ownerId: ID!, $namespace: String!, $key: String!, $type: String!, $value: String!) {
  metafieldsSet(metafields: [{ ownerId: $ownerId, namespace: $namespace, key: $key, type: $type, value: $value }]) {
    metafields { id namespace key type value }
    userErrors { field message }
  }
}

变量示例：

{
  "ownerId": "gid://shopify/Product/1234567890",
  "namespace": "custom",
  "key": "subtitle",
  "type": "single_line_text_field",
  "value": "轻盈透气，全天舒适"
}

Admin GraphQL：创建 Metaobject 定义与条目

mutation CreateMetaobjectDefinition {
  metaobjectDefinitionCreate(
    definition: {
      type: "size_chart"
      name: "Size Chart"
      fieldDefinitions: [
        { name: "Title", key: "title", type: "single_line_text_field", required: true },
        { name: "Content", key: "content", type: "multi_line_text_field" }
      ]
    }
  ) {
    metaobjectDefinition { id type name }
    userErrors { field message }
  }
}
mutation CreateMetaobjectEntry {
  metaobjectCreate(
    metaobject: {
      type: "size_chart"
      fields: [
        { key: "title", value: "上装尺码表" },
        { key: "content", value: "胸围/肩宽/衣长…" }
      ]
    }
  ) {
    metaobject { id handle type }
    userErrors { field message }
  }
}

将条目关联到产品：

mutation LinkMetaobjectToProduct($ownerId: ID!, $refId: ID!) {
  metafieldsSet(
    metafields: [{
      ownerId: $ownerId,
      namespace: "custom",
      key: "size_chart",
      type: "metaobject_reference",
      value: $refId
    }]
  ) {
    metafields { id }
    userErrors { field message }
  }
}

$refId 需为 metaobject 的 GID，如 gid://shopify/Metaobject/xxxx

Storefront API（GraphQL）读取示例

query ProductWithMetafields($handle: String!) {
  product(handle: $handle) {
    id
    title
    metafield(namespace: "custom", key: "subtitle") { value type }
    metafield(namespace: "custom", key: "size_chart") {
      reference {
        ... on Metaobject {
          handle
          type
          fields { key value }
        }
      }
    }
  }
}

常见问题排查

  • 主题中显示为空：检查命名空间/键拼写、字段是否发布、是否有权限
  • Storefront 读不到：确认字段已在相应资源的 metafields 策略里允许被读取
  • GraphQL 报错 userErrors：检查 type 与 value 是否匹配

参考（精简自官方文档）

  • 官方指南： Shopify Help - Metafields 
  • 核心要点：
    • 定义：为资源扩展自定义数据；优先考虑标准字段，标准字段不够再用元字段
    • 作用范围：产品、变体、集合、客户、订单、商店等均支持（支持度以官方为准）
    • 结构：namespace + key + type + value（可选描述与验证规则）
    • 类型：文本、数字、布尔、日期时间、文件/图片引用、资源引用、json、metaobject_reference
    • 验证：可设最小/最大、正则、选项集等，确保后台录入合规
    • 显示：可作为主题渲染数据源；部分场景可在资源列表中显示与筛选（视后台支持）
    • 权限：前台读取需在 Storefront 访问策略允许；应用写入需相应 API 权限
    • 本地化：部分类型支持翻译；多语言站点请结合语言设置规划
    • 升级与兼容：建议配合 Online Store 2.0 主题；旧主题需升级以便可视化使用
    • 类别元字段：按产品分类提供标准属性（依赖 metaobjects 条目）
    • 置顶与 POS：后台可置顶元字段；POS 显示置顶客户元字段与全部产品元字段
最后更新时间：
Headless Commerce架构完整指南