为博客文章生成并校验 JSON-LD schema…

当需要为博客文章生成 Article/BlogPosting、Person、Organization、BreadcrumbList、ImageObject、可选 FAQPage/VideoObject 的 JSON-LD 结构化数据并做校验时使用。

适用场景

解决思路

1. 读取博客文章，提取所有 schema 相关数据：标题（headline）、作者（name、job title、社交链接、credentials）、日期（datePublished、dateModified/lastUpdated）、描述（meta description）、FAQ 部分（问答对）、图片（封面图 URL、尺寸、alt text；内联图片）、组织信息（站点名称、URL、logo）、字数（根据内容长度估算）、标签/分类（用于 BreadcrumbList 分类）、slug（从文件名或 frontmatter 获取）。
2. 生成 BlogPosting schema：使用 `@type: BlogPosting`、`@id: {siteUrl}/blog/{slug}#article`、`headline`、`description`、`datePublished`、`dateModified`、`author`（引用 `{siteUrl}/author/{author-slug}#person`）、`publisher`（引用 `{siteUrl}#organization`）、`image`（引用 `{siteUrl}/blog/{slug}#primaryimage`）、`mainEntityOfPage`（WebPage，`@id` 为 `{siteUrl}/blog/{slug}`）、`wordCount`、`articleBody`（内容前 200 字符作为摘录）。
3. 注意 Google 的 Article structured data 文档未定义必需的 Article 属性；在适用时包含 `headline`、`datePublished`、`author`、`publisher`、`image`，并用 Rich Results Test 校验；除非目标展示面要求，否则把缺失字段视为警告。
4. BlogPosting 的推荐属性：`description`、`dateModified`、`mainEntityOfPage`、`wordCount`、`articleBody`（摘录）。
5. 生成 Person schema：`@type: Person`、`@id: {siteUrl}/author/{author-slug}#person`、`name`、`jobTitle`、`url`、`sameAs` 包含 Twitter/LinkedIn/GitHub 链接。
6. Person 可选属性：`alumniOf`（教育机构，Organization 类型）、`worksFor`（雇主；如果是同一实体，引用 Organization 的 `@id`）。
7. 生成 Organization schema：`@type: Organization`、`@id: {siteUrl}#organization`、`name`、`url`、`logo` 为 ImageObject（`url: {siteUrl}/logo.png`、`width: 600`、`height: 60`）、`sameAs` 包含组织社交链接。
8. Logo 要求：使用有效且可抓取的图片 URL，并遵循目标展示面当前的 Organization 与 Article 文档；除非项目或当前文档要求，不要编造固定 logo 尺寸。
9. 生成 BreadcrumbList：`@type: BreadcrumbList`、`@id: {siteUrl}/blog/{slug}#breadcrumb`；`itemListElement` 中 position 1 为 Home（`item: {siteUrl}`），position 2 为 Category Name（`item: {siteUrl}/blog/category/{category-slug}`），position 3 为 Post Title（`item: {siteUrl}/blog/{slug}`）。
10. 如果没有分类，则把第二个面包屑项设为 `Blog`，URL 为 `{siteUrl}/blog`。
11. 生成 FAQPage 实体 schema：从博客文章的 FAQ 部分提取问答对；`@type: FAQPage`、`@id: {siteUrl}/blog/{slug}#faq`、`mainEntity` 包含 `Question`（`name`）和 `acceptedAnswer`（`Answer`，`text` 为完整答案，40-60 词并尽量含统计数字）。
12. FAQPage 重要说明：Google 已于 2026-05-07 对所有站点下线 FAQ 富结果；FAQPage 不是 Google 富结果路径。只有在存在可见 FAQ 内容、且至少有一个有效 `Question` 和匹配的可见答案时才输出 FAQPage。
13. 将 FAQPage 视为实体清晰度标记，不要承诺 Google 富结果；博客搜索资格仍以 Article/BlogPosting schema 为优先。
14. 如果文章内嵌视频，为每个 YouTube 视频生成 VideoObject：`@type: VideoObject`、`@id: {siteUrl}/blog/{slug}#video-{index}`、`name`、`description`（描述前 200 字符）、`thumbnailUrl: https://img.youtube.com/vi/{videoId}/hqdefault.jpg`、`uploadDate`（ISO 8601）、`contentUrl: https://www.youtube.com/watch?v={videoId}`、`embedUrl: https://www.youtube.com/embed/{videoId}`、`duration: PT{M}M{S}S`、`interactionStatistic`（InteractionCounter，`interactionType: WatchAction`，`userInteractionCount: {viewCount}`）。
15. 将每个 VideoObject 加入 `@graph` 数组；`@id` 片段使用 `#video-1`、`#video-2` 等。
16. 从嵌入内容的 noscript fallback 提取视频元数据；如果可通过 `blog-google` 使用 YouTube Data API，也可从该 API 提取。
17. 生成 ImageObject（封面图）：`@type: ImageObject`、`@id: {siteUrl}/blog/{slug}#primaryimage`、`url`、`width: 1200`、`height: 630`、`caption`（描述性文字，与 alt text 匹配）。
18. 图片要求：URL 必须可抓取且公开可访问；`width` 和 `height` 应反映实际图片尺寸；`caption` 应与图片 alt text 匹配或高度一致；优先尺寸 1200x630（OG 兼容）或 1920x1080。
19. 校验并警告：在推荐 schema 类型前，按目标展示面检查支持情况。
20. HowTo：不是当前 Google 富结果策略；当页面确实包含 how-to 内容时，它是有效的 schema.org 类型。
21. Dataset：不用于通用博客富结果；对 dataset 页面和 Dataset Search 资格有效。
22. QAPage：与 FAQPage 不同；当页面包含一个问题且答案由用户提交时有效。
23. SpecialAnnouncement、PracticeProblem、Sitelinks Search Box：不要为普通博客文章推荐；仅当当前官方文档和页面内容匹配时使用。
24. 校验检查 1：所有 `@id` 引用都解析到 `@graph` 内的实体。
25. 校验检查 2：`dateModified` 等于或晚于 `datePublished`。
26. 校验检查 3：`headline` 简洁；当可能被截断或变得不清晰时发出警告。
27. 校验检查 4：`description` 简洁、页面特定，且不在多个文章间重复。
28. 校验检查 5：所有 URL 都是绝对 URL（不是相对 URL）。
29. 校验检查 6：图片尺寸是正整数。
30. 校验检查 7：BreadcrumbList 的 position 从 1 开始顺序递增。
31. 校验检查 8：如果输出 FAQPage，必须存在可见问答内容，并至少包含 1 个有效 `Question`。
32. AI 引用优化说明：相关 schema 有助于实体清晰度和有支持处的富结果资格，但结构化数据不是 Google 生成式 AI 搜索可见性的必需条件。优先 Article/BlogPosting、Person、Organization、BreadcrumbList。
33. 当存在对应资产时添加 ImageObject 或 VideoObject；仅当存在可见 FAQ 内容时添加 FAQPage。
34. 输出：将所有 schema 合并到单个 `<script type="application/ld+json">` 标签中，使用 `@graph` 模式。
35. `@graph` 结构：`@context` 为 `https://schema.org`，`@graph` 数组包含 BlogPosting、Person、Organization、BreadcrumbList、FAQPage、VideoObject、ImageObject。
36. `@graph` 模式优点：单个 script 标签替代多个标签，HTML 更干净；通过稳定 `@id` 引用进行实体链接（例如 author 通过 `@id` 引用 Person）；Google 和 AI 系统能正确解析 `@graph` 数组；作为单个块更易维护和更新。
37. 输出选项：Embedded HTML：可直接粘贴到 `<head>` 或 `</body>` 前；Standalone JSON：用于 CMS schema 字段或 API 注入；MDX component：如果项目使用 MDX，则包装成组件。
38. 按用户偏好，将生成的 schema 保存到博客文章文件中，或保存到单独的 schema 文件。

适用边界 · 注意事项

• 页面没有可见 FAQ 内容时，不要输出 FAQPage，也不要把它当作 Google 富结果路径。
• 不要为普通博客文章推荐 HowTo、Dataset、QAPage、SpecialAnnouncement、PracticeProblem、Sitelinks Search Box 等与页面内容/官方支持不匹配的类型。
• 若目标展示面有特定必需字段或官方文档要求，不能只依赖本经验；应以当前官方文档和 Rich Results Test 为准。