JSON-LD必须服务端直出、置于<head>、为合法纯JSON；Article需headline与<h1>逐字一致、datePublished为ISO 8601带时区、author为Person或Organization对象；多实体用@graph数组，避免合并错误。
JSON-LD 必须由服务端直接输出、放在 <head> 里、内容是合法纯 JSON——这三点不满足，其他所有配置都白搭。
<script type="application/ld+json"> 必须在服务端渲染时写死
Googlebot 不执行 JS，只解析首屏 HTML 流。任何靠 useEffect、mounted、document.createElement('script') 动态插入的 JSON-LD 都不可见。
- Next.js：用
next/head或useHead，确保脚本出现在初始 HTML 中，别在客户端组件里拼 - Nuxt：在
head: {}配置项里声明，或用useHead，避免在onMounted里操作 DOM - PHP/Jinja/Nunjucks：调用
json_encode($data, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES)，禁止字符串拼接 - 静态站点生成器（如 Hugo、Jekyll）：用原生模板函数序列化数据，别手写
{"name": "{{ title }}"}—— 特殊字符会破坏 JSON
Article 类型字段缺失就等于没写
加了 "@type": "Article" 不代表能出富摘要。Google 只认三要素齐全且格式严格的组合。
-
headline：必须和页面<h1>文本逐字一致（包括空格、标点），否则交叉校验失败 -
datePublished：必须是 ISO 8601 格式，推荐带时区，如"2026-07-01T14:40:00+08:00"；"2026-07-01"可能被部分解析器降权 -
author：不能是字符串"张三"，必须是对象：{"@type": "Person", "name": "张三"}；机构作者用@type: "Organization" -
image：值必须是 HTTPS 绝对 URL，且服务器返回 200；"./cover.jpg"或需登录才能访问的地址会被静默丢弃
多实体共存时用 @graph 数组，别硬塞进一个对象
博客页常同时描述文章、作者、网站、面包屑。强行合并会导致字段冲突或校验失败，@graph 是 Google 明确支持的平级声明方式。
立即学习“前端免费学习笔记（深入）”；
- 每个实体独立成对象，通过
@id建立关联（如文章@id指向#article，作者指向#author） - 用
mainEntityOfPage指明主实体（如 BlogPosting 对应@id: "#article"） - 避免多个
<script type="application/ld+json">标签——Google 会尝试合并，但容错率低 - 示例结构开头必须是：
{"@context": "https://schema.org", "@graph": [ ... ]}
本地验证时最容易忽略的三个细节
别等上线再查。用 Google URL Inspection Tool 粘贴完整 HTML 源码即可实时反馈，但以下问题常导致误判：
- 浏览器插件干扰：广告屏蔽、隐私类扩展可能过滤掉
<script type="application/ld+json">，测试前务必禁用 - 相对路径未转绝对：
"image": "/img/logo.png"在工具里显示为无效 URL，必须补全协议和域名 - JSON 语法隐形错误：末尾逗号、单引号、中文引号、未转义换行符——用 JSONLint 或 VS Code 的 JSON 验证器先过一遍
最麻烦的不是写错字段，而是字段写对了但和服务端吐出的 HTML 内容不一致——比如 headline 和实际 <h1> 差一个空格，Google 就会拒掉整个富摘要。交叉校验这事，机器比人严得多。
