> For AI agents: the complete documentation index is available at https://rspress.rs/zh/llms.txt, the full documentation bundle is available at https://rspress.rs/zh/llms-full.txt.
# 自定义 Head 标签 / SEO
为网页增加 Head 标签（如 meta 标签）对于 SEO 优化和社交媒体分享非常重要。比如 [Open Graph](https://ogp.me/) 是一种网页元数据协议，用于控制页面在社交媒体平台上分享时的显示效果。
目前 Rspress 会自动注入以下 Head 标签：
| 标签 | 描述 |
| -------------------------------------------------------------- | ------------------------------------------------- |
| `` | 标识站点生成器及版本号 |
| `` | 页面描述，参见下方 [description 的获取方式](#description-的获取方式) |
| `` | Open Graph 类型，固定为 `website` |
| `` | Open Graph 标题，使用当前页面标题（如果存在） |
| `` | Open Graph 描述，同上 |
| `` | 多语言站点中当前页面的其它语言版本 |
| `` | 性能优化：预加载当前页面对应的异步路由 chunk |
## description 的获取方式
默认情况下，Rspress 会提取 `h1` 标题下方第一段有内容的段落作为页面描述（参见 [`markdown.extractDescription`](https://rspress.rs/zh/api/config/config-build.md#markdownextractdescription)）。如果提取结果不满足需求，可以在 [frontmatter](https://rspress.rs/zh/api/config/config-frontmatter.md#description) 中指定 `description` 字段来覆盖：
```md title="example.mdx"
---
description: 自定义页面描述。
---
```
:::tip
你可以使用 [rspress-description-generator](https://github.com/rstackjs/agent-skills#rspress-description-generator) agent skill 来自动为所有页面生成 description。详见 [Agent Skills](https://rspress.rs/zh/guide/start/ai.md#agent-skills)。
:::
如果想增加 Head 标签可以通过以下几种方式：
## 全局 Head 配置
在 `rspress.config.ts` 中，你可以为所有页面设置 HTML 的 metadata（即 head 标签）。详情请查看 [基础配置 - head](https://rspress.rs/zh/api/config/config-basic.md#head)。
## frontmatter 配置
你可以调整 frontmatter 中的 [title](https://rspress.rs/zh/api/config/config-frontmatter.md#title) 和 [description](https://rspress.rs/zh/api/config/config-frontmatter.md#description) 字段来修改单个页面的标题和描述。
```md title="example.mdx"
---
title: 自定义页面标题
description: 自定义页面描述，用于 meta description 和 Open Graph。
---
```
也可以使用 [frontmatter - head](https://rspress.rs/zh/api/config/config-frontmatter.md#head) 自定义页面的 metadata 标签以进行 SEO 优化。
例如，如果你想在 `` 标签中添加 ``，你可以这样使用 frontmatter：
```md title="example.mdx"
---
head:
- - meta
- property: og:title
content: This is title
- - meta
- property: og:description
content: This is description
---
```
你也可以使用相同的配置添加 `` 标签：
```md title="example.mdx"
---
head:
- - meta
- name: keywords
content: Rspress, React, static site generator
---
```
## Head 组件
如果你需要更复杂的 Head 定制，可以使用 Rspress 提供的 [Head 组件](https://rspress.rs/zh/ui/runtime-components/head.md) 在页面或布局组件中动态设置 Head 标签。
## useHead hook
如果你已经在 React 组件内部，并且更偏向使用对象形式声明 head 内容，可以使用 [`useHead`](https://rspress.rs/zh/ui/hooks/use-head.md)：
```tsx
import { useHead } from '@rspress/core/runtime';
export function PageMeta() {
useHead({
title: '自定义页面标题',
meta: [
{
name: 'description',
content: '用于 SEO 和社交分享的自定义页面描述。',
},
],
});
return null;
}
```
和 `Head` 组件相比，`useHead` 在需要依赖 props、状态或复用工具函数来生成最终标签时通常更方便。
## Rsbuild html.tags 配置
通过 `builderConfig.html.tags`，你可以向 HTML 中注入自定义内容，比如添加统计代码、脚本或样式：
```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';
export default defineConfig({
builderConfig: {
html: {
tags: [
{
tag: 'script',
attrs: {
src: 'https://cdn.example.com/analytics.js',
},
},
],
},
},
});
```
更多配置详情请参考 [Rsbuild html.tags 文档](https://rsbuild.rs/zh/config/html/tags)。
:::tip 与 Rspress head 配置的区别
- **Rspress head 配置**：可以获取路由相关信息，支持根据不同页面动态设置 head 标签
- **Rsbuild html.tags**：是构建时的静态配置，适用于全局统一的标签注入（如统计代码）
如果需要根据页面路由动态调整 head 内容，请使用 [全局 head 配置](#全局-head-配置)、[Head 组件](#head-组件) 或 [useHead hook](#usehead-hook)。
:::