名称: pseo-schema 描述: 为程序化SEO页面实施JSON-LD结构化数据和模式标记，包括文章、FAQ、面包屑、产品和其他上下文特定模式类型。在添加或修复模式标记、实施结构化数据、或当Google Search Console报告模式错误时使用。参数提示: “[类型: 文章 | FAQ | 面包屑 | 产品 | HowTo | 全部]” 允许的工具: 读取, 全局, 查找, Bash, 编辑, 写入

pSEO 模式标记

实施JSON-LD结构化数据，为每个程序化页面提供显式的语义理解给搜索引擎。

核心原则

JSON-LD格式: 总是使用JSON-LD，而不是Microdata或RDFa
上下文适当的类型: 匹配模式类型到页面的实际内容
数据驱动的生成: 模式是从驱动页面的相同数据构建的
有效且完整: 每个模式块必须通过Google的富结果测试
不伪造: 只包含基于真实数据的字段

基线模式（每个页面）

每个pSEO页面应包括这些基础类型：

WebSite — 每个站点一次（在主页或通过共享布局），声明站点级搜索和名称
WebPage — 在每个页面上，声明页面URL、名称、描述和dateModified
BreadcrumbList — 在每个具有导航层次结构的页面上

这些是除了下面特定内容类型之外的。

按页面上下文的模式类型

页面类型	主要模式	支持模式
内容/文章页面	`Article`	`BreadcrumbList`, `FAQPage`, `WebPage`
产品页面	`Product`	`BreadcrumbList`, `AggregateRating`, `WebPage`
FAQ/Q&A页面	`FAQPage`	`BreadcrumbList`, `WebPage`
How-to/教程页面	`HowTo`	`BreadcrumbList`, `FAQPage`, `WebPage`
类别/中心页面	`CollectionPage`	`BreadcrumbList`, `ItemList`, `WebPage`
本地/位置页面	`LocalBusiness`	`BreadcrumbList`, `FAQPage`, `WebPage`

实施步骤

1. 创建模式生成器函数

构建一个模块，包含从页面数据生成模式对象的纯函数：

// lib/schema.ts

export function generateArticleSchema(data: PageData, url: string) {
  return {
    "@context": "https://schema.org",
    "@type": "Article",
    headline: data.h1,
    description: data.metaDescription,
    url,
    datePublished: data.publishedDate,
    dateModified: data.lastModified,
    author: { "@type": "Organization", name: "..." },
    publisher: { "@type": "Organization", name: "..." },
  };
}

// 重要: FAQPage 模式仅在 FAQ 内容实际可见于页面本身时才有效。
// Google 要求问题和答案在渲染的 HTML 中存在，而不仅仅在 JSON-LD 中。
// 永远不要向未渲染 FAQ 的页面添加 FAQPage 模式。
export function generateFAQSchema(faqs: FAQ[]) {
  if (!faqs?.length) return null;
  return {
    "@context": "https://schema.org",
    "@type": "FAQPage",
    mainEntity: faqs.map((faq) => ({
      "@type": "Question",
      name: faq.question,
      acceptedAnswer: {
        "@type": "Answer",
        text: faq.answer,
      },
    })),
  };
}

export function generateWebPageSchema(data: PageData, url: string) {
  return {
    "@context": "https://schema.org",
    "@type": "WebPage",
    name: data.title,
    description: data.metaDescription,
    url,
    dateModified: data.lastModified,
  };
}

export function generateBreadcrumbSchema(
  items: { name: string; url: string }[]
) {
  return {
    "@context": "https://schema.org",
    "@type": "BreadcrumbList",
    itemListElement: items.map((item, i) => ({
      "@type": "ListItem",
      position: i + 1,
      name: item.name,
      item: item.url,
    })),
  };
}

2. 创建模式渲染器组件

构建一个可重用的组件，将 JSON-LD 注入到页面头部：

export function JsonLd({ data }: { data: Record<string, unknown> | null }) {
  if (!data) return null;
  return (
    <script
      type="application/ld+json"
      dangerouslySetInnerHTML={{ __html: JSON.stringify(data) }}
    />
  );
}

3. 按页面组合模式

每个页面模板从其多个生成器中组合模式：

// 在页面组件中
const schemas = [
  generateArticleSchema(data, canonicalUrl),
  generateBreadcrumbSchema(breadcrumbItems),
  data.faqs?.length ? generateFAQSchema(data.faqs) : null,
].filter(Boolean);

// 渲染每个为独立的 script 标签
{schemas.map((schema, i) => <JsonLd key={i} data={schema} />)}

4. 模式字段规则

每种类型的必需字段：

Article: 标题、URL、日期发布、日期修改、作者、出版商
FAQPage: 主要实体，至少包含1个问题/答案对
BreadcrumbList: 项目列表元素，带有位置、名称、项目
Product: 名称、描述；优惠或评论（如果可用）
HowTo: 名称、步骤（每个步骤有文本）

字段完整性规则：

headline 必须匹配页面的 H1 或标题
url 必须匹配规范 URL
dateModified 必须是有效的 ISO 8601 日期
永远不要包含空字符串或占位符值
永远不要包含带有伪造数据的字段（例如，虚假评论）

5. 处理多种模式类型

单个页面可以有多个模式块。将它们渲染为独立的 <script type="application/ld+json"> 标签，而不是在一个标签中的数组（以实现最大兼容性）。

验证

模式必须：

通过 Google 的富结果测试 (https://search.google.com/test/rich-results)
通过 Schema.org 验证
不包含已弃用的属性
不包含带有空或占位符值的字段
使用绝对 URL，而不是相对路径

6. E-E-A-T 模式支持

Google 的 2025 更新高度重视经验、专业知识、权威性和可信度。模式标记可以增强这些信号：

每个页面的作者/组织模式：

export function generateAuthorSchema(author: AuthorInfo) {
  return {
    "@context": "https://schema.org",
    "@type": author.type === "person" ? "Person" : "Organization",
    name: author.name,
    url: author.url,
    ...(author.credentials && { jobTitle: author.credentials }),
    ...(author.sameAs && { sameAs: author.sameAs }),
  };
}

向文章模式添加 author 和 publisher（已经包括，但强调这现在是关键的，不是可选的）。

dateModified 必须准确 — Google 增加了对新鲜度信号的权重。如果内容实际上没有改变，永远不要将 dateModified 设置为今天的日期。使用数据源中真实的最后修改日期。

对于 YMYL 内容，额外包括：

reviewedBy 在医疗/健康内容上（带有 MedicalBusiness 或 Physician 类型的 Person）
citation 或 isBasedOn 对于源自权威来源的内容
credentialCategory 在作者的 Person 模式上（如果适用）

文件组织

lib/
  schema.ts            # 所有模式生成器函数
  schema.test.ts       # 验证测试
components/
  JsonLd.tsx           # 可重用的 JSON-LD 渲染器

与其他技能的关系

依赖于: pseo-data（结构化字段馈送模式生成）
与一起工作: pseo-templates（模式组件在页面模板内渲染）
面包屑数据来自: pseo-linking（面包屑轨迹结构）