---
title: SEO 优化
description: 设置标题、描述和元标签，优化搜索结果与社交预览；Jamdesk 自动生成站点地图和 Open Graph 图片。
---

> **For AI agents:** the complete documentation index is at [llms.txt](https://jamdesk.com/docs/llms.txt). Append `.md` to any page URL for its markdown version.

在 frontmatter 中设置标题、描述和元数据，优化文档在搜索引擎中的展示效果和社交预览。

## Jamdesk 自动完成的工作

<Columns cols={3}>
  <Card title="元标签" icon="tags">
    将 frontmatter 中的标题和描述转换为元标签。
  </Card>
  <Card title="Open Graph" icon="share">
    为每个页面生成社交分享图片。
  </Card>
  <Card title="站点地图与 Robots" icon="sitemap">
    每次构建时生成 XML 站点地图和 robots.txt。
  </Card>
  <Card title="JSON-LD" icon="code">
    为每个页面添加 Schema.org 结构化数据，帮助搜索引擎展示富媒体结果。
  </Card>
  <Card title="IndexNow" icon="bolt">
    每次构建后向搜索引擎提交发生变化的 URL。
  </Card>
  <Card title="AI 端点" icon="robot" href="/cn/ai/overview">
    提供 `llms.txt` 和 MCP 服务器，供 AI 工具读取文档。
  </Card>
</Columns>

## 优化内容

### 编写有效的 Frontmatter

```yaml
---
title: User Authentication    # Under 60 characters
description: Set up OAuth, JWT, and session-based authentication  # 120-160 characters
---
```

<Tip>
**将关键词放在前面。**“身份验证设置”比“如何设置身份验证”更合适。
</Tip>

### 页面标题

- 控制在 60 个字符以内，避免在搜索结果中被截断
- 将主要关键词放在靠近开头的位置
- 确保文档中每个页面的标题各不相同

### 描述

- 以 120–160 个字符为目标
- 概括读者将了解到的内容
- 自然地加入相关关键词

<Note>
**自动生成的备用描述。**如果 frontmatter 中没有 `description`，Jamdesk 会自动提取页面正文的第一个段落，最多 155 个字符。提取时会跳过标题、代码块、图片和 MDX 组件。提取的内容会用于 `<meta name="description">`、Open Graph 和 Twitter 卡片。为获得最佳效果，仍建议显式编写描述。
</Note>

## 控制索引收录

### 全站设置

在 `docs.json` 中配置默认的爬虫行为：

```json docs.json
{
  "seo": {
    "metatags": {
      "robots": "index, follow"
    }
  }
}
```

### 单页控制

在 frontmatter 中覆盖特定页面的索引设置：

```yaml
---
title: Internal Notes
noindex: true
---
```

以下页面适合使用 `noindex`：
- 草稿或尚未完成的页面
- 内部文档
- 为供参考而保留的已弃用内容

### 搜索索引与 AI 摄取

`robots` 元数据和 `noindex` 控制的是**搜索引擎**：页面是否出现在 Google 和站点的 `sitemap.xml` 中。它们不影响 AI 工具读取的 `llms.txt` 和 `llms-full.txt` 文件。要停止发布这些文件，请将 `seo.ai.llmsTxt` 设为 `false`（参阅[关闭 llms.txt](https://jamdesk.com/docs/cn/ai/llms-txt#关闭-llmstxt)）。这两种控制彼此独立：页面可以被搜索引擎收录，但不供 AI 摄取，反之亦然。

## 规范 URL

如果文档可以通过多个 URL 访问，请设置规范 URL：

```yaml
---
title: Getting Started
canonical: https://docs.example.com/getting-started
---
```

也可以在 `docs.json` 中设置全站规范 URL 的基础地址。Jamdesk 会将每个页面的路径附加到该地址，使每个页面都获得正确的规范 URL：

```json docs.json
{
  "seo": {
    "metatags": {
      "canonical": "https://docs.acme.com"
    }
  }
}
```

## 社交预览与 Open Graph

Jamdesk 会为每个页面自动生成一张带品牌标识的 1200×630 社交卡片。你可以在 frontmatter 中覆盖任意社交元标签。既可以使用**顶层扁平键**，也可以使用嵌套的 **`seo:`** 块。两种方式都有效；如果同一个键在两处都已设置，则以顶层值为准。

<Card title="OpenGraph 预览" icon="share-nodes" href="https://jamdesk.com/utilities/opengraph-preview" horizontal>
  使用 OpenGraph 预览工具，查看任意页面的卡片在 X、Facebook、LinkedIn 等平台上的展示效果，并验证其 Open Graph 标签。
</Card>

<CodeGroup>
```yaml Flat (top-level)
---
title: API Reference
description: REST API endpoints and authentication
"og:title": API Reference — Acme
"og:description": Everything you need to call the Acme API
"og:image": /images/api-social-card.png
"twitter:card": summary_large_image
"twitter:creator": "@acme"
keywords: ["api", "rest", "authentication"]
canonical: https://docs.acme.com/api-reference
---
```

```yaml Nested (seo block)
---
title: API Reference
description: REST API endpoints and authentication
seo:
  "og:title": API Reference — Acme
  "og:image": /images/api-social-card.png
  "twitter:card": summary_large_image
  x-custom-tag: any custom meta value
---
```
</CodeGroup>

### 支持的标签

| 分组 | 标签 |
|-------|------|
| Open Graph | `og:title`、`og:description`、`og:image`、`og:image:width`、`og:image:height`、`og:image:alt`、`og:url`、`og:type`、`og:site_name`、`og:locale`、`og:video`、`og:audio` |
| 文章 | `og:type: article`，搭配 `article:published_time`、`article:modified_time`、`article:author`、`article:section`、`article:tag` |
| Twitter / X | `twitter:card`、`twitter:title`、`twitter:description`、`twitter:image`、`twitter:image:alt`、`twitter:site`、`twitter:creator`、`twitter:player`、应用卡片标签 |
| 其他 | `keywords`、`author`、`robots`、`googlebot`、`google-site-verification`、`theme-color`，以及任意自定义标签（将自定义标签放在 `seo:` 下） |

<Note>
**自定义 OG 图片尺寸。**`og:image:width` 和 `og:image:height` 仅在 [`customImage`](#自定义社交卡片) 为 `"replace"` 时生效。请将它们与所描述的 `og:image` 放在同一位置，即页面 frontmatter 或 `seo.metatags` 中。生成的卡片始终为 1200×630。
</Note>

<Note>
**自定义标签。**任意元标签（例如 `x-pinterest`）会输出为 `<meta name="...">`。请将它们放在 `seo:` 块下。扁平放置在顶层时，只有已识别的 SEO 键会被读取。
</Note>

### Twitter / X 卡片类型

`twitter:card` 标签控制链接分享时 X（及其他平台）使用的布局：

| 值 | 展示效果 |
|-------|--------------------|
| `summary` | 左侧是小型方形缩略图，右侧是标题和描述，布局紧凑。 |
| `summary_large_image` | 顶部是占满宽度的大图，下方是标题和描述，展示效果更醒目。 |

对于带品牌标识的 1200×630 卡片，使用 `summary_large_image` 可让图片占满宽度。

### 全站默认图片

在 `docs.json` 中为所有页面设置备用社交图片。如果某个页面自行设置了 `og:image`，则会覆盖此图片：

```json docs.json
{
  "seo": {
    "metatags": {
      "og:image": "https://docs.acme.com/images/default-card.png"
    }
  }
}
```

<Tip>
**发布前先预览。**构建完成后，将页面 URL 粘贴到 [OpenGraph 预览](https://jamdesk.com/utilities/opengraph-preview)工具中，检查卡片在各平台的展示效果并验证 Open Graph 标签。该工具还会检查图片尺寸，并说明如何修复发现的问题。
</Tip>

### 自定义社交卡片

除非在 `docs.json` 中添加 `seo.socialCard`，否则生成的卡片会保持当前外观。只需设置要更改的键：

```json docs.json
{
  "seo": {
    "socialCard": {
      "theme": "dark",
      "brandColor": true,
      "accentBar": false,
      "siteName": false,
      "customImage": "replace"
    }
  }
}
```

| 键 | 默认值 | 效果 |
|-----|---------|--------|
| `theme` | `"light"` | `"dark"` 在深色背景上使用浅色文字，并使用 `logo.dark` 图片。 |
| `brandColor` | `false` | `true` 使用 `colors.primary` 为底部横条和章节徽标着色。如果设置了 `colors.light`，深色卡片会使用该颜色。如果未设置 `colors`，卡片会使用主题的强调色。`false` 则保留默认的红色。 |
| `accentBar` | `true` | `false` 移除卡片底部的彩色横条。 |
| `siteName` | `true` | `false` 隐藏徽标下方的网站名称。如果徽标本身已包含名称，可以使用此设置。 |
| `customImage` | `"background"` | `"background"` 在 `og:image` 上叠加页面标题。`"replace"` 将 `og:image` 用作整张卡片。 |

卡片只能绘制 SVG、PNG 和 JPG 徽标。Jamdesk 在构建网站时会将仓库中的 PNG 和 JPG 徽标文件转换为 WebP，因此卡片通常会改为显示网站图标，并保留网站名称，即使设置了 `siteName: false` 也是如此。要在卡片上显示完整徽标，请使用 SVG 徽标；深色卡片则使用 `logo.dark`。

如果品牌色在卡片上不够醒目，徽标文字会改用普通文字颜色。底部横条仍会保留品牌色，除非该颜色与卡片背景过于接近，此时横条会变为灰色。

默认情况下，Jamdesk 会在 `og:image` 上叠加页面标题。如果图片已有文字或设计，请设置 `"customImage": "replace"`，按原样展示图片。

将 `og:image` 用作卡片背景时，请选择与图片相匹配的 `theme`：深色图片使用 `dark`，浅色图片使用 `light`。

在 `replace` 模式下，Jamdesk 不会在图片上绘制标题。如果 `seo.metatags` 设置了 `og:image`，所有页面都会使用该图片；自行设置了 `og:image` 的页面则使用自己的图片。只有两处都未设置的页面才会获得生成的卡片。请使用 1200×630 的 PNG 或 JPG 图片。部分平台不显示 WebP 或 SVG 图片。

社交平台会缓存链接预览，因此更改这些设置后，之前分享过的链接可能仍会显示旧卡片一段时间。请使用 [OpenGraph 预览](https://jamdesk.com/utilities/opengraph-preview)工具检查新卡片。

<Note>
旧版 Jamdesk CLI 会在运行 `jamdesk validate` 和 `jamdesk dev` 时拒绝 `seo.socialCard`。请使用 `npm i -g jamdesk@latest` 升级。
</Note>

## 站点地图与 Robots.txt

每次构建时，Jamdesk 网站都会自动生成 `sitemap.xml` 和 `robots.txt`。

| 文件 | 用途 |
|------|---------|
| `sitemap.xml` | 为搜索引擎列出所有页面及其最后修改日期 |
| `robots.txt` | 允许所有爬虫访问，并将其引导至站点地图 |

### 查找位置

这些文件的 URL 取决于文档位于域名根路径，还是位于 `/docs` 子路径下：

<Tabs>
  <Tab title="域名根路径">
    如果文档位于域名根路径（例如 `docs.acme.com` 或 `acme.jamdesk.app`）：

    ```bash
    https://docs.acme.com/sitemap.xml
    https://docs.acme.com/robots.txt
    ```
  </Tab>
  <Tab title="/docs 子路径">
    如果文档位于主站的 `/docs` 下（如本站的 `jamdesk.com/docs`）：

    ```bash
    https://jamdesk.com/docs/sitemap.xml
    https://jamdesk.com/docs/robots.txt
    ```
  </Tab>
</Tabs>

### 站点地图包含的内容

- 所有已发布的页面（不包括 frontmatter 中设置了 `noindex` 或 `hidden` 的页面）
- frontmatter 中提供的最后修改日期
- 每周更新频率

### 从站点地图中排除页面

在 frontmatter 中添加 `noindex`，即可同时将页面从站点地图和搜索引擎中排除：

```yaml
---
title: Internal Notes
noindex: true
---
```

设置了 `hidden: true` 的页面也会自动排除。

## JSON-LD 结构化数据

每个页面都会通过 `<script type="application/ld+json">` 标签自动加入 [schema.org](https://schema.org) 结构化数据，其中包含两种结构：

- `WebSite`：网站名称、URL 和描述（来自 `docs.json`）。
- `BreadcrumbList`：根据 `navigation` 配置生成的从首页到当前页面的导航路径。

无需配置。搜索引擎会利用这些数据，在搜索结果中展示面包屑导航等富媒体结果。

<Tip>
**验证标记。**将任意页面的 URL 粘贴到 [Google 富媒体搜索结果测试](https://search.google.com/test/rich-results)中，确认结构化数据已被检测到。
</Tip>

## IndexNow

每次构建后，Jamdesk 会自动将发生变化的页面 URL 提交给 [IndexNow](https://www.indexnow.org)，加快搜索引擎的索引收录。这会通知 Bing、Yandex 和其他参与的搜索引擎内容已发生变化，而无需等待它们的下一轮抓取。

- 每次成功构建后都会执行
- 只提交实际发生变化的页面
- 以非阻塞方式运行，不会延迟构建
- 无需配置

## 最佳实践

发布前请核对以下清单：

<Note>
**发布前检查清单**

- **标题唯一。**每个页面都有独特且描述准确的标题，长度不超过 60 个字符。
- **描述准确。**描述用 120–160 个字符概括页面内容。
- **标题层级合理。**标题遵循清晰的层级：一个 H1，之后依次为 H2 → H3。
- **链接文字明确。**内部链接使用有意义的锚文本，避免使用“点击这里”。
- **图片替代文本。**每张图片都有替代文本，以支持无障碍访问和图片搜索。
- **社交图片。**为重要页面设置自定义 `og:image`，或使用自动生成的卡片。使用 [OpenGraph 预览](https://jamdesk.com/utilities/opengraph-preview)工具进行验证。
</Note>

## 相关文章

<Columns cols={2}>
  <Card title="Frontmatter 参考" icon="file-lines" href="/cn/content/frontmatter">
    查看所有可用的 frontmatter 选项
  </Card>
  <Card title="docs.json 参考" icon="gear" href="/cn/config/docs-json-reference">
    查看全站配置选项
  </Card>
  <Card title="OpenGraph 预览工具" icon="share-nodes" href="https://jamdesk.com/utilities/opengraph-preview">
    预览并验证社交卡片在各平台上的展示效果
  </Card>
</Columns>