# 结构化数据指南

本指南介绍如何使用 JSON-LD 结构化数据提升搜索引擎对内容的理解。

---

## 📋 目录

- [什么是结构化数据](#什么是结构化数据)
- [JSON-LD 基础](#json-ld-基础)
- [常用 Schema 类型](#常用-schema-类型)
- [验证工具](#验证工具)
- [最佳实践](#最佳实践)

---

## 什么是结构化数据

结构化数据是一种标准化的数据格式，帮助搜索引擎更好地理解网页内容。

**好处：**
- ✅ 丰富的搜索结果显示
- ✅ 提升点击率
- ✅ 语音搜索优化
- ✅ 知识图谱展示

---

## JSON-LD 基础

### 基本语法

```html
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "文章标题",
  "author": {
    "@type": "Person",
    "name": "作者姓名"
  }
}
</script>
```

### 在 Next.js 中使用

```typescript
// app/page.tsx
export default function Page() {
  const structuredData = {
    "@context": "https://schema.org",
    "@type": "Article",
    "headline": "文章标题",
  };

  return (
    <>
      <script
        type="application/ld+json"
        dangerouslySetInnerHTML={{
          __html: JSON.stringify(structuredData)
        }}
      />
      <main>...</main>
    </>
  );
}
```

**或使用命令生成：**
```bash
/structured-data [页面路径] [schema-type]
```

---

## 常用 Schema 类型

### 1. Article（文章）

```json
{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "SEO 优化完整指南",
  "image": "https://example.com/image.jpg",
  "author": {
    "@type": "Person",
    "name": "张三"
  },
  "publisher": {
    "@type": "Organization",
    "name": "Claude Code SEO",
    "logo": {
      "@type": "ImageObject",
      "url": "https://example.com/logo.jpg"
    }
  },
  "datePublished": "2025-01-04",
  "dateModified": "2025-01-04"
}
```

### 2. Organization（组织）

```json
{
  "@context": "https://schema.org",
  "@type": "Organization",
  "name": "Claude Code SEO",
  "url": "https://claude-code-seo.com",
  "logo": "https://claude-code-seo.com/logo.png",
  "description": "专业的 SEO 优化工具",
  "address": {
    "@type": "PostalAddress",
    "streetAddress": "123 Main Street",
    "addressLocality": "San Francisco",
    "addressRegion": "CA",
    "postalCode": "94102",
    "addressCountry": "US"
  },
  "contactPoint": {
    "@type": "ContactPoint",
    "telephone": "+1-415-555-0123",
    "contactType": "customer service"
  }
}
```

### 3. LocalBusiness（本地商家）

```json
{
  "@context": "https://schema.org",
  "@type": "PlumbingService",
  "name": "SF Plumbing Services",
  "image": "https://example.com/logo.jpg",
  "telephone": "+1 (415) 555-0123",
  "address": {
    "@type": "PostalAddress",
    "streetAddress": "123 Main Street",
    "addressLocality": "San Francisco",
    "addressRegion": "CA",
    "postalCode": "94102",
    "addressCountry": "US"
  },
  "geo": {
    "@type": "GeoCoordinates",
    "latitude": 37.7749,
    "longitude": -122.4194
  },
  "openingHoursSpecification": {
    "@type": "OpeningHoursSpecification",
    "dayOfWeek": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"],
    "opens": "08:00",
    "closes": "18:00"
  },
  "priceRange": "$$"
}
```

### 4. Product（产品）

```json
{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Claude Code SEO 插件",
  "image": "https://example.com/product.jpg",
  "description": "专业的 SEO 优化工具",
  "brand": {
    "@type": "Brand",
    "name": "Claude Code SEO"
  },
  "offers": {
    "@type": "Offer",
    "price": "99.00",
    "priceCurrency": "USD",
    "availability": "https://schema.org/InStock"
  },
  "aggregateRating": {
    "@type": "AggregateRating",
    "ratingValue": "4.8",
    "reviewCount": "52"
  }
}
```

### 5. FAQPage（常见问题）

```json
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [{
    "@type": "Question",
    "name": "什么是 SEO？",
    "acceptedAnswer": {
      "@type": "Answer",
      "text": "SEO（搜索引擎优化）是通过优化网站内容和结构，提升在搜索引擎中排名的技术。"
    }
  }, {
    "@type": "Question",
    "name": "如何快速提升 SEO？",
    "acceptedAnswer": {
      "@type": "Answer",
      "text": "可以通过优化元数据、创建高质量内容、建设外链等方式快速提升 SEO。"
    }
  }]
}
```

---

## 验证工具

### 1. Google Rich Results Test

访问：https://search.google.com/test/rich-results

### 2. Google Schema Validator

访问：https://validator.schema.org/

### 3. 使用命令验证

```bash
# 生成结构化数据
/structured-data app/page.tsx Article

# 验证所有结构化数据
/seo-audit
```

---

## 最佳实践

### 1. 必需字段

确保每种 Schema 类型的必需字段都完整：

```json
// ❌ 缺少必需字段
{
  "@type": "Article",
  "headline": "标题"
  // 缺少 author, publisher, datePublished
}

// ✅ 完整的必需字段
{
  "@type": "Article",
  "headline": "标题",
  "author": { "@type": "Person", "name": "作者" },
  "publisher": { "@type": "Organization", "name": "发布者" },
  "datePublished": "2025-01-04"
}
```

### 2. 避免错误数据

```json
// ❌ 错误的未来日期
"datePublished": "2026-01-01"

// ✅ 正确的日期
"datePublished": "2025-01-04"
```

### 3. 多种类型

可以同时使用多种 Schema：

```html
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Article",
  ...
}
</script>

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  ...
}
</script>
```

---

## 🔧 实用命令

```bash
# 生成结构化数据
/structured-data [页面路径] [schema-type]

# 验证结构化数据
/seo-audit

# 查看所有结构化数据问题
/seo-check
```

---

## 📚 相关资源

- [Schema.org 官方文档](https://schema.org/)
- [Google 结构化数据指南](https://developers.google.com/search/docs/appearance/structured-data/intro-structured-data)
- [JSON-LD 规范](https://json-ld.org/)

---

**相关指南：**
- [元数据优化指南](metadata-optimization.md)
- [评分系统 - 结构化数据](../scoring-system.md#2-结构化数据15-分)

---

**需要帮助？** 访问 [GitHub Issues](https://github.com/huifer/claude-code-seo/issues)