主题 schema.org 微数据的检查方法：三款工具与修复流程

引言：结构化数据写了，但从没验证过对不对

很多站点的情况是：主题「支持」结构化数据，页面里也确实能看到 JSON-LD，但从来没人验证过它是否合法、字段是否齐全、Google 会不会采用。于是出现一种尴尬——Search Console 的「增强功能」报告里，面包屑显示「已检测到 X 个，其中 Y 个存在错误」，而站长完全不知道错在哪。

结构化数据和普通 HTML 不同：写错了不会有任何可见后果，页面照常显示，只有校验工具会告诉你。而它的价值恰恰体现在搜索结果里的那几行额外信息（星级、面包屑路径、FAQ 折叠），错了就等于白做。本文给出三款官方工具的分工、一张必查字段清单，以及一次从「报错」到「修复」的完整演示。关于重复输出的问题，请看 主题结构化数据重复处理，本文专注校验与修复。

原理分析：三种写法，两款官方工具

结构化数据有三种嵌入方式，WordPress 生态里最常见的是前两种：

Google 官方明确推荐 JSON-LD。老主题常把 Microdata 写进模板标签里，改一次 HTML 结构就可能把 itemprop 弄丢，且报错时极难定位。

校验工具方面，有明确分工：

三者的关系是：开发阶段用 Schema Markup Validator 查语法，上线前用富媒体结果测试确认能否展示，长期用 Search Console 监控全站。只看其中一个都不够——富媒体测试不会报 Google 不支持的类型的错误，而 Validator 不关心 Google 是否采用。

保姆级实操

1. 先确认页面里有几份、什么类型：用 curl 抓 HTML，抽出 JSON-LD 里的 @type，确认类型是否符合页面性质（文章页应是 Article，产品页是 Product，首页常有 WebSite + Organization）。
2. 跑 Schema Markup Validator：把 URL 或代码粘进去，重点看红色错误（必填字段缺失）和黄色警告（推荐字段缺失）。
3. 跑富媒体结果测试：确认 Google 能识别的类型，以及「预览」里是否能看到预期展示效果。
4. 按必查字段清单逐项补：Article 至少要有 headline、datePublished、author、publisher；Product 至少要有 name、image、offers（含 price 与 priceCurrency）；Breadcrumb 的每一项都要有 position、name、item。
5. 修复方式优先用过滤器：不要改主题模板。Yoast 用 wpseo_schema_article 之类的过滤器补字段，Rank Math 用 rank_math/json_ld。
6. 验证闭环：修完清缓存，重跑两个工具，最后在 Search Console 里点「验证修复」，等 Google 重新抓取（通常一到两周）。

# 抽出现有 JSON-LD 的类型与关键字段，先做自检
curl -s https://example.com/sample-post/ \
  | grep -o '"@type":"[^"]*"' | sort | uniq -c

# 检查是否同时存在 Microdata（老主题常见）
curl -s https://example.com/ | grep -c 'itemtype="https://schema.org'
curl -s https://example.com/ | grep -o 'itemtype="[^"]*"' | sort | uniq -c

# 本地起一个临时服务，把未上线的页面给工具检测（工具支持 URL，也可用代码粘贴）
php -S 127.0.0.1:8000 -t public_html

{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "name": "首页",
      "item": "https://example.com/"
    },
    {
      "@type": "ListItem",
      "position": 2,
      "name": "博客",
      "item": "https://example.com/blog/"
    },
    {
      "@type": "ListItem",
      "position": 3,
      "name": "本文标题",
      "item": "https://example.com/sample-post/"
    }
  ]
}

{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "主题自带的结构化数据能直接删掉吗？",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "可以，但建议保留一份来源清晰的 JSON-LD，删除前先确认没有其他来源重复输出。"
      }
    },
    {
      "@type": "Question",
      "name": "校验通过就一定能展示富媒体吗？",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "不一定。校验通过只代表语法合法，能否展示还取决于 Google 是否支持该类型以及是否满足展示门槛。"
      }
    }
  ]
}

<!-- Microdata 写法示例：老主题常见，改结构时极易漏掉属性 -->
<article itemscope itemtype="https://schema.org/Article">
  <h1 itemprop="headline">文章标题</h1>
  <span itemprop="author" itemscope itemtype="https://schema.org/Person">
    <span itemprop="name">作者名</span>
  </span>
  <time itemprop="datePublished" datetime="2026-10-01T09:00:00+08:00">2026年10月1日</time>
  <div itemprop="articleBody">正文内容</div>
</article>

<?php
// 补字段要用过滤器，不要改主题模板
add_filter( 'wpseo_schema_article', function( $data ) {
    // 补齐必填的 publisher 与 author
    if ( empty( $data['publisher'] ) ) {
        $data['publisher'] = array(
            '@type' => 'Organization',
            'name'  => get_bloginfo( 'name' ),
            'logo'  => array(
                '@type' => 'ImageObject',
                'url'   => get_site_icon_url(),
            ),
        );
    }
    if ( empty( $data['dateModified'] ) ) {
        $data['dateModified'] = get_the_modified_date( 'c' );
    }
    return $data;
} );

常见踩坑

• 只跑富媒体测试就认为没问题：它只检查 Google 支持的类型，Article 的必填字段缺失在某些类型下不会全报。必须再跑 Validator。
• 在本地环境检测：工具需要公网可访问，本地 localhost 无法检测。用临时公网地址或直接粘贴代码。
• 改了没清缓存：工具抓到的是缓存副本，改完必须清一次页面缓存与 CDN，再重跑工具。
• 把 Microdata 和 JSON-LD 混用：同一实体用两种写法描述，Google 会当成两个实体，属性冲突。选一种，推荐 JSON-LD。
• FAQPage 泛滥：Google 已大幅限制 FAQ 富媒体的展示范围，非官方站点写了也基本不展示。别为它投入过多。
• 案例：一个知识库站点上线半年，Search Console 里 Article 一直是「已检测到 0 个」。检查发现主题输出的 JSON-LD 里 @type 写成了 article（小写），而 schema.org 规范区分大小写，必须是 Article。一个字母导致整站结构化数据全部无效。修正后两周内检测到两千多个。大小写错误是最容易被忽略、后果又最严重的一类问题。
• 修完不看 Search Console：工具通过不代表 Google 已重新抓取，必须在后台点「验证修复」触发重新抓取流程。缓存未刷新的判断见 主题更新后样式缓存未刷新。

总结

结构化数据的检查流程固定为三步：自检类型与份数 → Schema Markup Validator 查语法 → 富媒体结果测试查展示 → Search Console 长期监控。必查字段按类型记：Article 看 headline/datePublished/author/publisher，Product 看 name/image/offers，Breadcrumb 看 position/name/item。修复一律用插件提供的过滤器完成，绝不改主题模板，否则升级即丢。上线后记得在 Search Console 点「验证修复」，这一步才能真正闭环。