JSON-LD 校验实战指南：捕获那些让你丢掉富媒体展示的结构化数据

结构化数据是"看不见的"SEO 工作里最容易失败的那一块。一个错位的逗号、一个格式错的日期、一个缺失的 image 字段，可以悄无声息地让一个页面在几周时间里失去富媒体展示资格——直到某天流量掉下来，才有人注意到。

结构化数据检查器（原名 "JSON-LD Validator"）是我们对每个上线页面跑的最快前置检查。本指南是它的操作手册：浅校验到底能给你什么、什么时候该升级到完整的 schema.org 校验、以及如何读懂每个 block 的报告而不错读。

检查器具体查什么

检查器从页面里抽出两种结构化数据格式，对每个 block 独立报告：

• JSON-LD——所有 <script type="application/ld+json"> 块。每个都会被解析，@type 会在已知类型集合里匹配。
• Microdata——所有带 itemscope 属性的元素，以及它们的 itemtype 和 itemprop 子节点。

对每个 block，检查器报告三件事：

1. 检测到的 @type（或对应的 Microdata itemtype）。
2. block 是否成功解析（JSON 合法、itemtype 存在）。
3. schema.org 或 Google 关心的字段的状态——必填字段、推荐字段、以及对格式敏感的字段（日期、URL、数字）。

检查是结构性的，不是穷举的。检查器确认 block 存在、@type 已知、JSON 能解析、明显的必填字段在。它不跑完整的 schema.org 规范。

检查器不查什么

一些看起来像校验工作、但其实在别处的事：

• 完整的 schema.org 合规——完整规范覆盖几百种类型、几千条规则。检查器只覆盖那些能抓到现实错误的规则，不覆盖那些"技术上正确"的。
• Google 富媒体展示资格——Google 有额外要求（图片质量、发布者资格、垃圾内容策略），这些只在 Search Console 里露面。检查器能确认你的 block 格式正确，不能保证 Google 一定给出富媒体展示。
• 跨 block 一致性——如果你的页面有一个 Organization block 和一个 WebSite block，检查器不会验证其中一个的 url 是否和另一个的 url 一致。这要靠人工审计。
• 实时渲染——检查器解析 HTML，不解析渲染后的 DOM。如果你的 JSON-LD 是由客户端 JavaScript 注入的，检查器在源码 HTML 里看不到它就不会报。
• AMP 专属扩展——AMP 页面里的 application/ld+json 合法，但检查器只解析标准格式。AMP 专属扩展请用 AMP 验证器。

block 通过检查器 = 结构上可靠。block 没通过 = 源码里有个你能修的问题。整个契约就这些。

什么时候跑

按"抓到真实 bug 的频率"排序，三个时机：

1. 发布前，对生产 URL 跑，CMS 模板锁定之后。JSON-LD 回归通常来自模板变更，不是 schema 内容本身。
2. 任何 head 或 schema 注入逻辑的改动之后——CMS 升级、插件替换、重设计、新增一个需要新 @type block 的产品类型。
3. 排查具体投诉时——Search Console 报结构化数据错误、富媒体展示曝光突然下降、合作伙伴指出某个页面缺一个知识面板条目。

不要在 CI 里每次提交都跑。检查器会发一次网络请求，今天通过不代表明天通过。把它留给上述几个时机。

如何读懂输出

结果页有三个区：汇总（按格式分组的 block 数）、每个 block 一张卡片、按字段报告。看的时候请记住几件事：

• 绿色 block 卡片 = block 解析成功、@type 已知、必填字段没有缺失。 它不意味着 Google 会把它编入富媒体展示。
• 黄色 block 卡片 = 一些必填或推荐字段缺失。 看字段级报告找出具体哪些。
• 红色 block 卡片 = block 完全没解析成功——JSON 不合法、缺 itemtype、或其他结构性问题。这个 block 对 SEO 毫无作用，可能还在打断某些下游消费者。
• 字段级小圆点——绿 = 在且格式正确、黄 = 在但格式有问题、红 = 必填且缺失、灰 = 推荐但缺失。旁边的 "required" / "recommended" 标签会告诉你是哪种。

抓真实 bug 最多的两种格式是 ISO 8601 日期和格式正确的 URL。如果你的 @datePublished 是 "2026-07-11 14:30" 而不是 "2026-07-11T14:30:00Z"，检查器会标黄。修格式，不要忽略警告。

常见失败与修复

按出现频率排序的几个常见失败：

1. CMS 模板把字符串拼接到 JSON-LD block 里，输出 JSON 不合法。 这是红色 block 最常见的原因。修法：把 JSON-LD 对象作为真正的数据结构（数组、对象）构建，最后一次性序列化——不要拼接字符串。

2. datePublished 格式错误。 常见变体是 "2026年7月11日"（人类可读）而 schema.org 要求 ISO 8601。检查器会标黄。修法：让日期走一个输出 ISO 8601 的序列化器，不要走字符串格式化工具。

3. logo 字段是字符串，但类型期望 ImageObject。 这是常见 bug 的反面——Organization 的 logo 字段两种都接受。其他类型不一定。检查器在 Organization 上两种都正确处理；其他类型请看规范。

4. Article 或 NewsArticle block 缺 image 字段。 Google 拿这个字段生成文章富媒体展示。没有 image 的 block 即便其他字段全对也出不了富媒体展示。检查器会标灰（推荐）——不要忽略。

5. sameAs 数组里有过期的社交账号。 这是内容问题不是校验问题，但检查器会把它标出来，因为这个字段是推荐的。如果账号已经死掉就删掉；如果还在，检查器只是在提醒你它在那儿。

嵌入发布流程

最干净的使用方式：把它和一次页面速度检查、一份内容快照 diff 并列为发布前最后三步之一。简单流程：

1. 在预发 URL 上跑一次检查器。
2. 确认页面上每个 block 都通过。
3. 如果有黄 block，看字段级报告，决定是发布前修，还是在 launch doc 里记下来。
4. 上线落地后，在生产 URL 上再跑一次。
5. 如果有 block 改了 @type 或字段要求，还要在生产 URL 上跑一次 Google 富媒体测试。

检查器是快速前置，不是终局。把它当成能抓 30 秒内能修的 bug 的检查——错 JSON、日期格式错、必填字段缺。更深的检查（图片质量、政策合规、资格）属于 Search Console 和富媒体测试。

什么时候该升级到自建系统

如果你一周跑检查器超过几次，就到了一个自建系统更划算的临界点。几个信号：

• 你有一个大站（几百个页面），需要对它们并发审计，不是一个 URL 一次。
• 你一个页面要发多个 Article 类型，需要把数组作为整体校验，不是一个 block 一次。
• 你有内部模板会生成 JSON-LD，你想要一个 CI 闸门在已知回归上让构建失败。
• 你需要校验跨 block 一致性（Organization 里的 url 等于 WebSite 里的 url、Article 里的 publisher 等于站点级 Organization）。

上述任何一种情况下，对的解法是一套对接你 CMS 或构建流水线的自定义校验器，带着你的 schema 实际需要的规则跑。免费检查器是个合适的起点，不是终局。

---

检查器地址：/tools/json-ld-validator。每次发布前在预发 URL 上跑，每次 CMS 变更后在生产 URL 上跑。代理每次审计只发一次 fetch；除了你提交的 URL，没有任何数据被存储或发给第三方。