JSON-LD 快速开始

JSON-LD 最常见的上手方式，是在 HTML 页面里添加一段 script 标签。浏览器不会把它当作可执行 JavaScript，而是作为结构化数据供搜索引擎、爬虫或其他消费方读取。

1. 选择页面主体

先判断页面主要描述的实体是什么：

页面	常见类型
博客文章	`Article`、`BlogPosting`、`NewsArticle`
商品详情	`Product`
公司官网	`Organization`、`LocalBusiness`
面包屑导航	`BreadcrumbList`
课程列表	`Course`、`ItemList`
FAQ 页面	`FAQPage`

不要为了“覆盖更多类型”而堆叠不相关结构。优先描述页面真实、主要、可见的内容。

2. 编写 JSON-LD

下面是一篇文章页的最小可用示例：

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "JSON-LD 快速开始",
  "description": "学习如何在网页中添加 JSON-LD 结构化数据。",
  "datePublished": "2026-09-22",
  "dateModified": "2026-09-22",
  "author": {
    "@type": "Person",
    "name": "Ada Chen",
    "url": "https://example.com/authors/ada"
  },
  "publisher": {
    "@type": "Organization",
    "name": "Example Docs",
    "logo": {
      "@type": "ImageObject",
      "url": "https://example.com/logo.png"
    }
  },
  "mainEntityOfPage": "https://example.com/json-ld/getting-started"
}
</script>

3. 放在页面哪里

通常放在 HTML 的 <head> 中最容易维护：

<head>
  <title>JSON-LD 快速开始</title>
  <script type="application/ld+json">
  {
    "@context": "https://schema.org",
    "@type": "Article",
    "headline": "JSON-LD 快速开始"
  }
  </script>
</head>

也可以放在 <body>，但要确保服务端渲染、客户端注入和缓存策略不会导致爬虫拿到旧数据或缺失数据。

4. 验证语法和搜索特性

建议分两类工具验证：

目标	工具
JSON-LD 语法和展开结果	JSON-LD Playground
Google 搜索富媒体结果	Google Rich Results Test 或 Search Console
Schema.org 类型和属性	Schema.org Validator

验证时不要只看“是否通过”。还要检查解析出的实体是否符合你的预期，例如作者是不是嵌套成了 Person，产品价格是不是字符串格式，页面 URL 是否稳定。

5. 建立维护流程

在真实项目里，JSON-LD 应该和页面数据来自同一份源数据：

const article = {
  title: "JSON-LD 快速开始",
  description: "学习如何在网页中添加 JSON-LD 结构化数据。",
  url: "https://example.com/json-ld/getting-started",
  publishedAt: "2026-09-22",
  updatedAt: "2026-09-22",
};

const jsonLd = {
  "@context": "https://schema.org",
  "@type": "Article",
  headline: article.title,
  description: article.description,
  datePublished: article.publishedAt,
  dateModified: article.updatedAt,
  mainEntityOfPage: article.url,
};

这样可以避免页面标题改了但结构化数据没改，或库存、价格、评分等敏感字段不同步。

上线前检查

JSON 语法有效，没有尾随逗号、注释或未转义换行。
@context 使用稳定地址，例如 https://schema.org。
@type 与页面主体一致。
标题、价格、评分、作者、日期等信息与页面可见内容一致。
URL 使用规范化后的绝对地址。
验证工具解析出的实体与预期一致。