JSON-LD 最佳实践

好的 JSON-LD 不只是“验证工具不报错”。它应该稳定、真实、可维护，并且能被目标消费方正确理解。

从同一份数据生成

页面内容和 JSON-LD 应该来自同一份源数据：

function createArticleJsonLd(article) {
  return {
    "@context": "https://schema.org",
    "@type": "Article",
    headline: article.title,
    description: article.summary,
    datePublished: article.publishedAt,
    dateModified: article.updatedAt,
    mainEntityOfPage: article.url,
  };
}

不要在模板里手写一份标题、再在 JSON-LD 里手写另一份标题。长期看，这几乎一定会不同步。

使用稳定的绝对 URL

推荐使用绝对 URL：

{
  "@id": "https://example.com/products/k1",
  "url": "https://example.com/products/k1",
  "image": "https://example.com/images/products/k1.jpg"
}

相对 URL 在不同解析环境中可能得到不同结果。对于图片、作者页、商品页、组织页等重要资源，使用规范化后的绝对地址更稳。

为核心实体设计 @id

实体	推荐 ID
网站	https://example.com/#website
组织	https://example.com/#organization
页面	页面规范 URL
文章	页面 URL 加 #article 或页面规范 URL
作者	作者主页 URL
商品	商品详情页 URL 或稳定商品 URI

稳定 @id 可以让不同页面上的实体信息互相连接，而不是变成一堆无法合并的匿名对象。

控制上下文复杂度

优先使用成熟上下文：

{
  "@context": "https://schema.org"
}

只有在需要自定义字段时才添加本地上下文：

{
  "@context": [
    "https://schema.org",
    {
      "docs": "https://example.com/vocab#",
      "readingTime": "docs:readingTime"
    }
  ]
}

自定义词汇应该有稳定命名空间和文档说明。

遵守目标平台规则

如果目标是 Google 搜索，不仅要符合 Schema.org，还要符合对应搜索功能的文档。不同类型对必填字段、推荐字段、图片、日期、价格、评价等要求不同。

如果目标是内部知识图谱，则应重点关注实体 ID、类型层级、关系一致性和数据更新策略。

避免误导性标记

不要标记页面上不存在或用户看不到的信息：

• 页面没有 FAQ，就不要添加 FAQPage。
• 商品没有真实评价，就不要添加 aggregateRating。
• 活动已经取消，就不要继续显示可报名状态。
• 页面展示价格是 399，JSON-LD 不应写 299。

结构化数据是页面内容的机器表达，不是给机器看的另一套内容。

建立验证流水线

上线前建议包含这些检查：

检查	方法
JSON 语法	JSON.parse 或构建期校验
页面注入	查看构建后的 HTML
Schema.org 结构	Schema.org Validator
搜索功能资格	Google Rich Results Test
上线后状态	Search Console 或日志监控

版本和回归测试

当模板、CMS 字段、商品系统或路由规则变化时，JSON-LD 也可能被影响。建议为关键页面保留快照测试：

expect(createArticleJsonLd(article)).toMatchObject({
  "@context": "https://schema.org",
  "@type": "Article",
  headline: "JSON-LD 最佳实践",
});

测试不必覆盖每个字段，但要覆盖容易影响搜索和消费方解析的关键字段。

发布检查清单

• 页面可见内容与结构化数据一致。
• 核心实体有稳定 @id。
• URL、图片、作者页使用绝对地址。
• 日期使用标准格式并包含必要时区。
• 价格、库存、评分等动态字段来自可信数据源。
• 验证工具能解析出预期实体。
• 对目标平台的特定规则已经逐项确认。