结构化数据有三种写法，而 JSON-LD 是 Google 和主流 AI 引擎的首选。但它绝不是一个随便扔进 <script> 的 JSON 就算完——结构写错，整段标记会被忽略掉，但页面上是看不到任何报错的。本文是 JSON-LD 的语法完整手册：从两大要素、核心关键词（@id / @graph / @language），到数据类型规则、对象嵌套、数组写法，以及最容易踩的 JSON 语法坑。关于各 Schema 类型的业务字段怎么填，请看 Schema.org Article 详解 与 BreadcrumbList 标记。
JSON-LD 是什么：一段"给机器读"的 JSON
JSON-LD 全称 JavaScript Object Notation for Linked Data。一段嵌在页面中的 JSON，它为机器描述"这个页面里有什么、是谁的、讲什么"。它本质是 JSON 的一个超集，在普通 JSON 之上加了以 @ 开头的"关键词"（如 @context / @type / @id）。和 Microdata（写在 HTML 属性上）不同，JSON-LD 是独立代码块，不和正文混在一起——这是它被推荐的最核心原因：易维护、不破坏正文、不依赖 HTML 结构。
两大要素：@context 与 @type
| 要素 | 作用 | 写法 | 写错的后果 |
|---|---|---|---|
| @context | 声明这段 JSON 遵循哪套词汇表 | "@context": "https://schema.org" | URL 拼错（http/多写少写）不认整段 |
| @type | 告诉机器"这一块标记的是什么东西" | "@type": "Article" 等 | 类型名不存在（如 "ArticlePage"）被静默丢弃 |
注意两点：@context 必须是完整的 https://schema.org（不能缺失 http 或 schema.org）；@type 大小写敏感，Article 不是 article，拼错会失效。
核心关键词全家福
@id实体身份证
给实体一个全局唯一标识符（如 "@id": "https://www.qibo.com/#org"）。不同代码块用同一个 @id 即可互引，避免重复定义、建立实体网络。GEO 里极重要。
@graph批量定义
一个 <script> 块里用 "@graph": [...] 定义多个实体。适合首页一次性声明 Organization + WebSite。
@language多语言
给文本标语言，如 {"@value":"名称","@language":"zh"}。站点是中文内容时，清晰标注有助于跨语言 AI 正确归并。
普通属性无 @ 前缀
name / headline / datePublished 等就是普通 JSON 键，按 Schema.org 规定的属性名写即可。
数据类型规则
| 类型 | 写法 | GEO 常见坑 |
|---|---|---|
| 字符串 | 必须双引号包裹 | 用了单引号 ' 或中文引号 " → JSON 解析失败 |
| 数字 | 不带引号，如 "position": 1 | "position": "1"（字符串）虽能解析，但类型不符可能被忽略 |
| 布尔 | true / false，不带引号 | "true" 变成字符串 |
| 日期 | ISO 8601："2026-07-16" | "2026年7月16日" 或 "07/16/2026" → 不被识别为日期 |
| URL | 完整 https://... | 相对路径 /news 在结构化数据里无效 |
对象嵌套：描述"实体套实体"的复杂关系
一篇文章的 author 不是字符串，而是一个有姓名、有主页的实体；publisher 不止有名称、还有 logo。JSON-LD 用嵌套对象表达这种关系。下面这段标准 Article 代码，注意 author 和 publisher 都是 {@type, name, url} 的嵌套对象，而 publisher.logo 又套了一层 ImageObject：
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "Article",
"headline": "文章标题",
"datePublished": "2026-07-16",
"author": {
"@type": "Organization",
"name": "启博",
"url": "https://www.qibo.com"
},
"publisher": {
"@type": "Organization",
"name": "启博",
"logo": {
"@type": "ImageObject",
"url": "https://www.qibo.com/logo.png"
}
}
}
</script>@id 实战：用标识符建立实体网络
如果首页声明了组织、每篇文章又重复写一遍组织信息，既臃肿又不利于 AI 建立"这是同一家公司"的认知。正确做法是用 @id 给组织一个锚点，文章里用同一 @id 引用：
// 首页 Organization 定义锚点
"@type": "Organization",
"@id": "https://www.qibo.com/#org",
"name": "启博"
// 文章页 publisher 直接引用同一锚点，无需重复
"publisher": {"@id": "https://www.qibo.com/#org"}这样 AI 读完全站，会把所有指向 #org 的引用归并到同一个"启博"实体上——实体网络越清晰，被引用时的权威度越高。这也是为什么分散在 各篇 GEO 文章 里的 publisher 都应该用同一 @id 锚定，而不是各写各的组织信息。
@graph 实战：一个 script 块定义多个实体
首页需要同时声明 Organization 和 WebSite，用 @graph 可以写在一个 <script> 里：
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@graph": [
{"@type": "Organization", "@id": "https://www.qibo.com/#org", "name": "启博", "url": "https://www.qibo.com"},
{"@type": "WebSite", "name": "启博官网", "url": "https://www.qibo.com"}
]
}
</script>数组 vs 单对象：什么时候用 []
1单对象 {}
一个实体只有一个值时用 {}。如一篇文章只有一位 publisher、一个 author。写成 "publisher": {"@type": "Organization", ...}。
2数组 [{}]
一个实体有多个值时用 [{...},{...}]。如 BreadcrumbList 的 itemListElement（多级面包屑）和 FAQPage 的 mainEntity（多个问答）。
3易错点
FAQPage 的 mainEntity 和 BreadcrumbList 的 itemListElement 即使只有一个元素，也必须是数组 [{}]。写成 {} 会被 Rich Results Test 直接判为无效。
易犯的 JSON 语法错误对照表
| 错误 | 现象 | 正确写法 |
|---|---|---|
| 尾随逗号 | {"a":1,} 最后多一个逗号 → JSON 解析失败 | 删掉最后一个逗号 |
| 单引号 / 中文引号 | 属性名或字符串用了 ' 或 " → 失效 | 一律用英文双引号 |
| 字符串内未转义引号 | 描述里写了 " 截断 JSON | 用 " 转义，或改用中文引号 |
| 写了 // 注释 | JSON 标准不支持注释 → 解析失败 | 删除注释，说明写进 description |
| 重复 key | 同一对象出现两次 "name" → 取值不确定 | 合并为一次 |
| BOM / 不可见字符 | 文件头有 BOM 导致 @context 解析异常 | 保存为无 BOM 的 UTF-8 |
放在哪、怎么加载（影响爬取）
- 位置不限：
<head>或<body>都可以，Google 在页面任意位置都能识别。GEO 内容统一放在正文末尾，与可见内容解耦、最易维护。 - 必须服务端渲染输出：如果页面靠前端 JavaScript 把 JSON-LD 注入 DOM，搜索引擎和 AI 爬取时读不到——结构化数据必须是服务端直接输出的 HTML 一部分。
- CSP 策略：若站点启用了严格的 Content-Security-Policy，确保允许
application/ld+json类型的脚本，否则会被浏览器拦截。
怎么写完就验证（写错看不见）
- 本地 JSON.parse：先把代码贴进浏览器控制台
JSON.parse(...)或任意 JSON 校验器，确认语法本身合法。 - Google Rich Results Test：粘贴 URL 或代码，直接报缺了什么、类型不对、数组错了。
- Schema Markup Validator：Schema.org 官方语法检查器，能发现 @context 写错、嵌套不合规这种低级错误。
- Search Console：上线后看"增强功能"报告，确认结构化数据被成功抓取、无告警。
- 人工核对：JSON-LD 里的标题、作者、时间，必须和页面肉眼可见内容一致。
常见问题
一段 JSON-LD 能同时标记多种 Schema 类型吗？
不在一个对象里塞多种类型。但可用 @graph 在一个 <script> 块里定义多个实体（如 Organization + WebSite）；或者用多个独立的 <script> 块，每块标一种类型。一篇文章需要 Service + BreadcrumbList + FAQPage 就写三段独立 script。
JSON-LD 里的字段顺序重要吗？
不重要。JSON 对象不依赖字段顺序，Schema.org 按 key 名解析。@context 放第一行、@type 放第二行是行业惯例，非强制。
能不能写 Schema.org 没有的自定义字段？
不能。Schema.org 只认官方定义的字段（如 headline / datePublished / author）。自定义 key 会被直接忽略，不报错也不起作用。若某概念无标准字段，用 description 兜底。
@id 一定要写吗？
单篇文章不强制。但只要你的站点有多个页面都指向同一组织/同一品牌，强烈建议用 @id 锚定——它是让 AI 把分散的引用归并到同一实体的关键机制，直接提升 GEO 的权威识别。
前端框架渲染的 JSON-LD 能被抓取吗？
若 JSON-LD 是页面初始 HTML 里服务端直出的，能；若靠客户端 JS 异步注入 DOM，搜索引擎和 AI 大概率读不到。务必保证结构化数据是服务端渲染输出。
免责声明：本文对 JSON-LD 语法的说明参考 json-ld.org 规范、schema.org 官方文档与 Google 结构化数据指南（2026 年）。具体字段要求与校验规则可能随平台更新而变化，上线前请以官方最新文档为准。代码模板为通用示例，替换真实值后使用。
