JSON-LD 常见问题排查
JSON-LD 的错误通常分为三类：JSON 语法错误、语义映射错误、目标平台规则不满足。排查时先确认页面最终输出，再看验证工具报告。
JSON 语法错误
application/ld+json 必须是合法 JSON。
错误示例：
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "Article",
headline: "未加引号的键",
}
</script>
问题包括：
headline没有双引号。- 末尾有尾随逗号。
- JSON 中不能写注释。
正确示例：
{
"@context": "https://schema.org",
"@type": "Article",
"headline": "合法 JSON"
}
@context 写错
常见问题：
| 问题 | 影响 |
|---|---|
拼写为 context |
JSON-LD 处理器不会把它当作上下文 |
| 使用不可访问的远程地址 | 处理器可能无法展开字段 |
| 自定义字段没有映射 | 消费方不知道字段语义 |
| 混用多个上下文导致覆盖 | 字段展开结果和预期不同 |
排查方法：用 JSON-LD Playground 展开文档，查看字段是否展开为期望 IRI。
@type 与页面不匹配
不要只因为某个类型看起来“更利于 SEO”就使用它。
| 页面内容 | 不建议 | 建议 |
|---|---|---|
| 普通文章 | Product |
Article 或更具体文章类型 |
| 公司介绍页 | FAQPage |
Organization、AboutPage |
| 商品分类页 | 单个 Product |
CollectionPage、ItemList，按平台规则决定 |
| 作者页 | Article |
Person、ProfilePage |
如果结构化数据和页面主体不一致，验证工具可能通过，但搜索质量系统仍可能忽略。
页面内容与 JSON-LD 不一致
这是生产环境最常见的问题：
- 页面显示缺货，JSON-LD 仍是
InStock。 - 页面价格已变化，JSON-LD 仍是旧价格。
- 页面标题修改了，
headline没同步。 - 页面删除 FAQ，JSON-LD 仍保留 FAQ。
解决方式：从页面同一份数据源生成 JSON-LD，并为动态字段建立缓存失效策略。
客户端渲染导致抓取缺失
如果 JSON-LD 由客户端 JavaScript 异步插入，某些爬虫或测试工具可能看不到最终内容。建议：
- 能服务端渲染就服务端渲染。
- 静态站点在构建期输出 JSON-LD。
- 如果必须客户端注入，使用目标平台工具测试实际抓取结果。
- 避免在用户交互后才生成结构化数据。
图片 URL 不可访问
结构化数据中的图片应该使用可公开访问的绝对 URL：
{
"image": [
"https://example.com/images/article-1x1.jpg",
"https://example.com/images/article-4x3.jpg"
]
}
避免使用：
- 本地路径，如
/Users/me/image.jpg。 - 需要登录的图片。
- 很快过期的签名 URL。
- 被
robots.txt或防盗链策略阻止的资源。
验证工具结果不一致
不同工具关注点不同：
| 工具 | 主要作用 |
|---|---|
| JSON-LD Playground | 检查 JSON-LD 展开、压缩、RDF 转换 |
| Schema.org Validator | 检查 Schema.org 类型和属性 |
| Google Rich Results Test | 检查 Google 搜索支持的富媒体结果资格 |
| Search Console | 观察线上抓取和索引后的状态 |
一个工具通过，不代表所有目标平台都接受。要按最终目标选择权威工具。
排查顺序
- 查看页面最终 HTML，确认脚本真实存在。
- 复制
script内容，用 JSON 解析器验证。 - 用 JSON-LD Playground 展开，确认语义映射。
- 用 Schema.org Validator 检查类型和属性。
- 如果目标是 Google 搜索，用对应 Search Central 文档和测试工具检查。
- 上线后看 Search Console 和日志，不只依赖本地测试。