# JSON-LD 常见问题排查

URL: https://caijiao.org/json-ld/guide/troubleshooting
Source: docs/json-ld/guide/troubleshooting.md
Description: 收集 JSON-LD 编写和上线过程中的常见错误，覆盖 JSON 语法、上下文、类型属性、页面一致性、搜索验证和客户端渲染问题。

JSON-LD 的错误通常分为三类：JSON 语法错误、语义映射错误、目标平台规则不满足。排查时先确认页面最终输出，再看验证工具报告。

## JSON 语法错误

`application/ld+json` 必须是合法 JSON。

错误示例：

```html
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Article",
  headline: "未加引号的键",
}
</script>
```

问题包括：

- `headline` 没有双引号。
- 末尾有尾随逗号。
- JSON 中不能写注释。

正确示例：

```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：

```json
{
  "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 | 观察线上抓取和索引后的状态 |

一个工具通过，不代表所有目标平台都接受。要按最终目标选择权威工具。

## 排查顺序

1. 查看页面最终 HTML，确认脚本真实存在。
2. 复制 `script` 内容，用 JSON 解析器验证。
3. 用 JSON-LD Playground 展开，确认语义映射。
4. 用 Schema.org Validator 检查类型和属性。
5. 如果目标是 Google 搜索，用对应 Search Central 文档和测试工具检查。
6. 上线后看 Search Console 和日志，不只依赖本地测试。