结构化数据不是给搜索引擎看的装饰,是给机器读的说明书
很多站长加结构化数据的方式是:搜索"JSON-LD 生成器",填几个字段,把代码贴进主题的 head,然后等富媒体摘要出现。等了两周没动静,就认为这条路没用,删掉了事。
实际上,绝大多数结构化数据失败的原因非常朴素:页面正文里没有的东西,JSON-LD 里写了;或者正文里有的东西,JSON-LD 里漏了。搜索引擎对结构化数据有一条铁律——标记的内容必须与页面上用户可见的内容一致。不一致的标记不仅不生效,还可能被判定为垃圾标记,影响整站信任度。
这篇文章按"分类型、逐字段、验证工具、常见冲突"的顺序讲清楚,最后给一份可以直接套用的 Typecho 与 WordPress 实现方式。
一、先分清三类标记,别一股脑都加
Article 系列:内容型页面必备
技术博客、资讯站的文章页用 Article、BlogPosting 或 NewsArticle。三者的区别是粒度,不是对错:日常博客用 BlogPosting;站点首页或专题页用 Article;时效性新闻用 NewsArticle(对时效字段要求更严)。
必填字段只有四个:headline、image、datePublished、author。这四个缺一个,Google 基本不会给富媒体展示。dateModified 不是必填但强烈建议,改过文章要更新它——它直接影响内容新鲜度的判断。
BreadcrumbList:几乎零成本,优先做
面包屑标记几乎是"免费"的:字段少、不会冲突、对搜索结果里的路径展示有直接帮助。首页 → 分类 → 文章,三层就够。注意 position 必须从 1 开始连续编号,中间跳号是校验失败最常见的原因。
WebSite 与 SearchAction:只有首页需要
很多人把这个加到每一页,其实只有首页需要。SearchAction(站内搜索框标记)要求你的站真的有一个可用的搜索入口,且 URL 模板里的占位符能被正确替换。加了但搜索不可用,等于给自己埋一个不一致。
顺带说一句 FAQPage:2023 年之后 Google 大幅收窄了 FAQ 富媒体结果的展示范围,只对权威站点常见。个人站加了通常不会展示,但也不会受罚。如果正文确实是问答结构,加着没坏处;如果为了标记硬编几条假问答,那就属于"标记与内容不一致",别做。
二、逐字段:写错的顺序按出现频率排
image:必须有,而且要是可访问的绝对 URL
"image": ["https://www.example.com/usr/uploads/2026/11/cover.jpg"]三个常见错误:写成相对路径 /usr/uploads/...(部分解析器不接受);用了第三方图床但图已经挂了(等于没有);宽高比极端(Google 建议 16:9、宽 1200 像素以上、image 多图时给三张不同比例的)。可用性检查很简单:
curl -sI "https://www.example.com/usr/uploads/2026/11/cover.jpg" | head -3
# 必须是 200,且 content-type 是 image/*datePublished:ISO 8601,带时区
"datePublished": "2026-11-18T09:30:00+08:00",
"dateModified": "2026-11-18T14:05:00+08:00"2026-11-18 这种只有日期的写法能被接受但不是最佳实践;写成 2026/11/18 或本地化的"2026年11月18日"就会失败。时区不能省——服务器时区和读者时区不同的情况下,差 8 小时可能导致"未来时间"判定,直接不展示。这是最隐蔽的一类失败:标记语法全对,就是不出现,因为日期被解析成了未来。
author:用 Person,别只写一个字符串
"author": {
"@type": "Person",
"name": "老周",
"url": "https://www.example.com/about.html"
}字符串形式("author": "老周")是能解析的,但没有 url 就少了一层实体关联。对个人博客来说,url 指向"关于"页是最划算的一步:它让搜索引掣能把多篇文章的作者关联到同一个实体上。
headline:长度与一致性
headline 应该与页面的 或 一致或高度接近。技术上允许 110 字符,但超过 60~70 字符在展示时会被截断。常见错误是把完整标题塞进去的同时还带上站点名后缀("文章标题 - 我的博客"),导致主标题被挤掉。
publisher 与 mainEntityOfPage:可选但推荐
"publisher": {
"@type": "Organization",
"name": "一个草根站长的博客",
"logo": { "@type": "ImageObject", "url": "https://www.example.com/logo.png" }
},
"mainEntityOfPage": { "@type": "WebPage", "@id": "https://www.example.com/2268.html" }
mainEntityOfPage 在被转载的场景里有意义:它告诉搜索引擎这个 URL 才是原始页面,有助于原始出处判定。
三、JSON-LD 放在哪、怎么组织
位置:head 或 body 都可以,但要一个
Google 接受 与 里的 JSON-LD。实践上放 head 更清楚,也不受主题渲染逻辑影响。一个页面上可以有多个 块,也可以用一个块里的 @graph 数组承载多个实体。不要同时用两种方式定义同一个实体——比如既有一个独立 WebSite 块,又在 @graph 里再来一遍,会造成实体定义重复。
用 @id 串联,而不是重复写
{
"@context": "https://schema.org",
"@graph": [
{
"@type": "WebSite",
"@id": "https://www.example.com/#website",
"url": "https://www.example.com/",
"name": "一个草根站长的博客"
},
{
"@type": "BlogPosting",
"@id": "https://www.example.com/2268.html#article",
"headline": "文章标题",
"datePublished": "2026-11-18T09:30:00+08:00",
"author": { "@id": "https://www.example.com/#person" },
"publisher": { "@id": "https://www.example.com/#organization" },
"isPartOf": { "@id": "https://www.example.com/#website" }
}
]
}
用 @id 引用同一个站点、同一个作者,是让标记"成体系"的关键。它让搜索引擎看到一个站点、一个作者、多篇文章的结构,而不是一堆互不相关的孤立块。
PHP 生成时的三个陷阱
动态生成 JSON-LD 最容易出的错都在字符串处理上:
// 正确:json_encode 处理转义与编码
$data = [
'@context' => 'https://schema.org',
'@type' => 'BlogPosting',
'headline' => $post['title'],
'datePublished' => date('c', $post['created']),
];
echo '';
三个陷阱:
- 不要手动拼接 JSON 字符串。标题里有引号、反斜杠、HTML 实体都会破坏结构。永远走
json_encode。 JSON_UNESCAPED_UNICODE让中文不被转成\uXXXX,输出更小、更易读;JSON_UNESCAPED_SLASHES让 URL 里的斜杠不被转义。这两个 flag 是关键。- 标题里的 HTML 实体要先解码。数据库里存着已经被 HTML 转义过的标题时,直接塞进 JSON 会出现双重编码,页面上展示出一串实体字符。
还有一个 Typecho 特有的坑:$post['created'] 是时间戳,date('c', ...) 用的是服务器时区。如果服务器设成 UTC 而站点是中文站,输出的时间会比实际早 8 小时——本身不致命,但如果同时也用 +08:00 硬编码,就变成了双重错误。要么全部用 UTC 并写 +00:00,要么设置 date_default_timezone_set('Asia/Shanghai') 并写 +08:00,不要混。
四、验证:三个工具,一个顺序
1) Rich Results Test:看能不能出富媒体
Google 官方工具,直接输入 URL 或粘贴代码,能看到每一项是否"可展示"、缺哪些字段。它比 SDTT(Structured Data Testing Tool,已下线)更接近实际展示逻辑。先过这一关,再谈效果。
2) Schema Markup Validator:看语法与语义
schema.org 官方的验证器,管的是"语法对不对、类型与属性匹不匹配"。两个工具用途不同:前者管展示,后者管正确性。都过一遍。
3) GSC 的"增强功能"报告:看长期状态
Search Console 左侧的"增强功能"里能看到 Article、面包屑等各类型的有效/无效数量与具体错误。刚上线时会是"未检测到项目",等 Google 重新抓取之后才有数据,通常几天到两周。不要今天加完明天就去看有没有效果。
命令行自检也可以做,用来快速确认 JSON 语法没坏:
curl -s https://www.example.com/2268.html \
| python3 -c "import sys,re,json; \
m=re.findall(r'', sys.stdin.read(), re.S); \
[json.loads(x) for x in m]; print('JSON-LD blocks OK:', len(m))"
把这段放进发版检查,比手动打开验证器快得多。
五、最容易踩的三种冲突
与 SEO 插件重复输出
WordPress 装了 Yoast 或 Rank Math,主题里又自己写了一遍 JSON-LD,结果是同一页面出现两套 BlogPosting。轻则校验报"多个实体",重则被判定为不一致。先查现状:curl -s URL | grep -c 'application/ld+json',大于 1 就要确认是不是重复定义同一实体。要么关掉插件的输出,要么删掉主题里的,选一个。
与页面可见内容不一致
标题在 JSON-LD 里是一套、 是另一套;作者标记写了"张三",页面署名是"李四";发布日期标了今天,页面显示的是两年前的。这三类都会被识别为不一致。规则很简单:JSON-LD 只能描述页面上已经存在的东西,不能用来"优化"实际不存在的内容。
与 robots、canonical 打架
页面被 noindex 了,标记再多也没意义;canonical 指向别的 URL,标记会被算到那个 URL 头上(如果那边内容不同,就是不一致)。加标记之前先确认页面本身"值得被索引"。这是很多"标记没问题就是不展示"的最终答案。
一张落地清单
- 文章页加
BlogPosting,四个必填字段齐全(headline / image / datePublished / author); - 每一页加
BreadcrumbList,position 连续从 1 开始; - 首页加
WebSite,有可用站内搜索才加SearchAction; - 用
@graph+@id串联站点与作者,不要重复定义; datePublished用 ISO 8601 带时区,服务器时区与标记时区不能冲突;image用绝对 URL,先curl -sI确认 200;- PHP 侧一律
json_encode+JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES; - 装插件前先
grep确认没有第二套输出; - 上线后过 Rich Results Test 与 Schema Validator,再等 GSC 抓取。
结构化数据这件事的性价比其实很高:一次性配置、不需要维护、对点击率有可见影响。它做不好的唯一原因,是把它当成"贴一段代码就完事"的任务。它实质上是在向机器描述你的内容——描述准确,机器才愿意把内容更好地展示出去。