shopify-json-ld

Shopify JSON-LD

为 Shopify 商店添加补充性结构化数据：主题无法自行生成的架构类型（Recipe、FAQPage、更丰富的 Article/Collection 节点），以 JSON-LD 的形式存储在每个实体的 metafield 中，并通过单个 Liquid 片段渲染。基本原则：只补充缺失内容，绝不重复主题已输出的内容。 对于元标签、描述和 Open Graph（这是另一项工作），请使用配套技能 shopify-seo-metadata。

商店访问权限

方式 A：自定义应用令牌（可编写脚本）。 在 Shopify 管理后台中：Settings → Apps and sales channels → Develop apps → 创建应用 → 授予此技能所需的最小权限范围，然后安装应用并复制 Admin API 访问令牌。将其导出；切勿将其写入已提交的文件：

export SHOPIFY_STORE="your-store.myshopify.com"
export SHOPIFY_ACCESS_TOKEN="<your Admin API access token>"   # env only, not on disk

最小权限范围：read_products、write_products、read_content、write_content。没有单独的 metafield 权限范围；metafield 访问权限由所属资源的权限范围决定（products → write_products，pages/articles → write_content）。渲染片段需要主题编辑权限（主题编辑器或主题的 Git 仓库），这与 API 权限分开。检查令牌是否有效：

curl -s "https://$SHOPIFY_STORE/admin/api/2025-07/graphql.json" \
  -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ shop { name } }"}'

方式 B：Shopify CLI OAuth（不存储令牌）。 执行 shopify store auth --store $SHOPIFY_STORE --scopes read_products,write_products,read_content,write_content，然后执行 shopify store execute。适用于由所有者登录且不使用令牌的商店。

工具包预检。 方式 B 依赖 Shopify CLI：先运行 shopify version，如果尚未安装则进行安装。要使用完整的 Admin GraphQL 架构并执行经过验证的操作，请将此技能与 Shopify 官方 AI 工具包插件配合使用。在 Claude Code 中，检查 claude plugin list；如果列表中没有该插件：

claude plugin marketplace add Shopify/Shopify-AI-Toolkit
claude plugin install shopify-plugin@shopify-ai-toolkit

建议使用，但并非必需：方式 A 只需要 curl 和令牌。工具包为 Agent 提供 API；此技能则提供操作指南。

仅补充原则：生成前先审计

现代 Shopify 主题已在 PDP 上输出 Product 架构（价格、变体、库存情况，以及使用 Judge.me、Yotpo 或 Stamped 等评价应用时的 aggregateRating），还会在全站输出 Organization/WebSite，并且通常还会输出 Article/BreadcrumbList。重复其中任何内容都会产生冲突节点，降低获得资格的可能性，而非改善效果。

因此，第一步始终是只读操作：获取首页、一个 PDP、一个系列页和一篇博客文章，并提取所有 <script type="application/ld+json"> 块。

curl -s "https://$SHOPIFY_STORE/products/<some-handle>" \
  | grep -o '<script type="application/ld+json">[^<]*' | head

无论主题已涵盖哪些内容，都不要触碰。补充架构应当是同一页面上的独立类型（例如与主题的 Product 节点并列的 FAQPage 或 Recipe 节点），绝不能是第二个 Product 节点。如果主题的 Product 架构有误或缺失，应修复主题。不要用重复内容来掩盖问题。

metafield + 片段模式

将 JSON-LD 存储在 metafield 中，并原样渲染。渲染时不会转换值，因此存储的字符串必须已经是有效的 JSON-LD。

1. 定义 metafield（Settings → Custom Data → 实体类型 → Add definition）：namespace 为 custom，key 为 json，type 为 multi_line_text_field。 为计划填充的每种实体类型（Products、Collections、Pages、Articles）分别创建定义。

2. 在 theme.liquid 中添加一个渲染片段，放在 </head> 之前：

{%- if request.page_type == 'product' and product.metafields.custom.json != blank -%}
  <script type="application/ld+json">{{ product.metafields.custom.json }}</script>
{%- elsif request.page_type == 'collection' and collection.metafields.custom.json != blank -%}
  <script type="application/ld+json">{{ collection.metafields.custom.json }}</script>
{%- elsif request.page_type == 'page' and page.metafields.custom.json != blank -%}
  <script type="application/ld+json">{{ page.metafields.custom.json }}</script>
{%- elsif request.page_type == 'article' and article.metafields.custom.json != blank -%}
  <script type="application/ld+json">{{ article.metafields.custom.json }}</script>
{%- endif -%}

3. 使用 metafieldsSet 写入值（GraphQL）。它会按 namespace/key 执行插入或更新，因此会更新已有的 metafield，而不是重复创建：这样可以避开经典的 REST 陷阱——在已有 metafield 时再次 POST 创建第二个。以紧凑格式存储 JSON（JSON.stringify(obj)，不添加美化缩进）。批量写入前先预览目标数量；如果数量远超预期，应停止并重新确定范围。完整流程和各实体的提示词见：references/pipeline-and-prompts.md。

两条不可妥协的架构规则

Google 会验证找到的所有类型化节点，包括深层嵌套的节点。单个节点格式错误，就会导致整个代码块验证失败。以下两条规则几乎可以避免所有此类问题：

• 不要使用没有附加信息的 Product 节点。 Google 要求每个 @type: "Product" 都包含 offers、review 或 aggregateRating。补充架构中很少会有这些信息（它们由主题负责），因此按名称引用产品时应使用 @type: "Thing"，而不是 Product。
• 不要使用不完整的 VideoObject 节点。 VideoObject 必须包含 name、description、thumbnailUrl、uploadDate，以及 contentUrl 或 embedUrl。如果没有真实的视频元数据，就不要输出 VideoObject：改用 Thing 或由 ListItem 条目组成的 ItemList。

这两种错误通常会导致 Search Console 报出“字段的对象类型无效”和“缺少字段”错误。

FAQPage 不再有助于获得富媒体搜索结果

Google 已于 2026 年移除非权威（电商）网站的 FAQ 富媒体搜索结果。 产品页或商店页面上的 FAQPage 标记将不再在搜索结果中显示可展开的问答摘要。它仍是有效的结构化数据，也仍有助于机器理解页面，但不要再将其宣传为能提升富媒体搜索结果或 SERP 可见度。这种说法已经过时。Recipe，以及在确实适用时的 Article，仍符合展示条件；在承诺能显示结果前，请根据 Google 文档核实各类型当前的展示条件（参见 Provenance）。

防范幻觉的生成

当 Agent 根据产品或页面内容生成 FAQ 或描述性架构时，只能陈述来源文本中包含的事实。 不得编造尺寸、重量限制、材料或功能。如果来源描述很简略，就少生成一些条目：三个有依据的问答胜过五个问答中有两个答案是编造的；而架构中的虚构规格是 Google（和客户）都能发现的事实性声明。提示词必须明确禁止编造，并优先选择“省略”而不是“猜测”。按实体区分的提示词框架请参见参考资料。

通过 Admin API 验证，而不是查看店面

写入后，店面可能会在数分钟到数小时内继续提供旧版 JSON-LD：Shopify 的 CDN 会缓存渲染后的页面。请通过 Admin API 回读 metafield，确认写入成功；不要通过 curl 产品页面来验证：

curl -s "https://$SHOPIFY_STORE/admin/api/2025-07/graphql.json" \
  -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ product(id:\"gid://shopify/Product/<ID>\") { metafield(namespace:\"custom\",key:\"json\"){ value } } }"}'

Metafield 的值才是事实依据。值正确后，店面会在自己的缓存周期结束后更新：这种延迟不是需要排查的错误。

非破坏性默认做法

• 先读取，再写入；批量更新中留空的 metafield 单元格会删除其值，而不是跳过该单元格。除非有意覆盖，否则只填充缺失值。
• 批量写入前先备份（先导出现有的 custom.json 值）。
• 切勿打印或提交 Admin API 访问令牌；应从环境变量中读取。

参考资料

• references/pipeline-and-prompts.md：生成流程（获取 → 筛选 → 生成 → 验证 → 写入）和按实体区分的提示词范例（Product FAQ、Recipe、Collection、Page、Article），按需加载。

来源与维护

最后验证时间：2026-07-05。GraphQL 固定使用 Admin API 2025-07；Shopify 每季度弃用旧版本，因此在依赖特定版本的说法前，请先确认版本。Google 的富媒体搜索结果展示资格会发生变化：电商网站的 FAQ 富媒体搜索结果已弃用，其他类型也会调整，因此在承诺能在 SERP 中显示结果前，请根据 Google 的结构化数据文档 重新核实各架构类型的展示条件。规范的类型定义见 schema.org。任何人都可以运行以下只读复核：

# 1. Confirm the token reaches the store.
curl -s "https://$SHOPIFY_STORE/admin/api/2025-07/graphql.json" \
  -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ shop { name } }"}'

# 2. Confirm a product page actually renders a JSON-LD block.
curl -s "https://$SHOPIFY_STORE/products/<some-handle>" \
  | grep -c 'application/ld+json'

然后在 Google 的 Rich Results Test（富媒体搜索结果测试）中验证任何有效 URL (https://search.google.com/test/rich-results)。这些技能总结了文档中没有的操作经验；它们不能取代 schema.org 或 Google 参考资料。