# JSON-LD 快速开始
URL: https://caijiao.org/json-ld/guide/getting-started
Source: docs/json-ld/guide/getting-started.md
Description: 通过一个可直接嵌入 HTML 页面的 Article 示例，学习 JSON-LD 的编写、放置、验证和迭代流程。
JSON-LD 最常见的上手方式，是在 HTML 页面里添加一段 `script` 标签。浏览器不会把它当作可执行 JavaScript，而是作为结构化数据供搜索引擎、爬虫或其他消费方读取。
## 1. 选择页面主体
先判断页面主要描述的实体是什么：
| 页面 | 常见类型 |
| --- | --- |
| 博客文章 | `Article`、`BlogPosting`、`NewsArticle` |
| 商品详情 | `Product` |
| 公司官网 | `Organization`、`LocalBusiness` |
| 面包屑导航 | `BreadcrumbList` |
| 课程列表 | `Course`、`ItemList` |
| FAQ 页面 | `FAQPage` |
不要为了“覆盖更多类型”而堆叠不相关结构。优先描述页面真实、主要、可见的内容。
## 2. 编写 JSON-LD
下面是一篇文章页的最小可用示例：
```html
```
## 3. 放在页面哪里
通常放在 HTML 的 `` 中最容易维护：
```html
JSON-LD 快速开始
```
也可以放在 ``，但要确保服务端渲染、客户端注入和缓存策略不会导致爬虫拿到旧数据或缺失数据。
## 4. 验证语法和搜索特性
建议分两类工具验证：
| 目标 | 工具 |
| --- | --- |
| JSON-LD 语法和展开结果 | JSON-LD Playground |
| Google 搜索富媒体结果 | Google Rich Results Test 或 Search Console |
| Schema.org 类型和属性 | Schema.org Validator |
验证时不要只看“是否通过”。还要检查解析出的实体是否符合你的预期，例如作者是不是嵌套成了 `Person`，产品价格是不是字符串格式，页面 URL 是否稳定。
## 5. 建立维护流程
在真实项目里，JSON-LD 应该和页面数据来自同一份源数据：
```ts
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 使用规范化后的绝对地址。
- 验证工具解析出的实体与预期一致。