# JSON-LD 最佳实践

URL: https://caijiao.org/json-ld/guide/best-practices
Source: docs/json-ld/guide/best-practices.md
Description: 汇总 JSON-LD 在网页、API、结构化数据和知识图谱中的生产建议，覆盖数据一致性、ID 设计、上下文治理和验证流程。

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

## 从同一份数据生成

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

```ts
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：

```json
{
  "@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` 可以让不同页面上的实体信息互相连接，而不是变成一堆无法合并的匿名对象。

## 控制上下文复杂度

优先使用成熟上下文：

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

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

```json
{
  "@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 也可能被影响。建议为关键页面保留快照测试：

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

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

## 发布检查清单

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