> 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.

# @rspress/plugin-sitemap 

[源码](https://github.com/web-infra-dev/rspress/tree/main/packages/plugin-sitemap)

自动生成用于 SEO 的 [站点地图 (sitemap)](https://developers.google.com/search/docs/crawling-indexing/sitemaps/overview)，有利于搜索引擎抓取。

## 安装


```sh [npm]
npm add @rspress/plugin-sitemap -D
```

```sh [yarn]
yarn add @rspress/plugin-sitemap -D
```

```sh [pnpm]
pnpm add @rspress/plugin-sitemap -D
```

```sh [bun]
bun add @rspress/plugin-sitemap -D
```

```sh [deno]
deno add npm:@rspress/plugin-sitemap -D
```

## 使用

在 `rspress.config.ts` 中写入以下的配置：

```ts
// rspress.config.ts
import path from 'path';
import { defineConfig } from '@rspress/core';
import { pluginSitemap } from '@rspress/plugin-sitemap';

export default defineConfig({
  plugins: [
    pluginSitemap({
      siteUrl: 'https://example.com', // 替换为你的网站 URL
    }),
  ],
});
```

## 配置

这个插件接受一个对象参数，类型如下:

```ts
type ChangeFreq =
  'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never';

type Priority =
  | '0.0'
  | '0.1'
  | '0.2'
  | '0.3'
  | '0.4'
  | '0.5'
  | '0.6'
  | '0.7'
  | '0.8'
  | '0.9'
  | '1.0';

// https://www.sitemaps.org/protocol.html
interface Sitemap {
  loc: string;
  lastmod?: string;
  changefreq?: ChangeFreq;
  priority?: Priority;
}

interface CustomMaps {
  [routePath: string]: Sitemap;
}

export interface PluginSitemapOptions {
  siteUrl?: string;
  customMaps?: CustomMaps;
  defaultPriority?: Priority;
  defaultChangeFreq?: ChangeFreq;
}
```

### siteUrl

- **类型**： `string`
- **默认值**：[`siteOrigin`](https://rspress.rs/zh/api/config/config-basic.md#siteorigin) 与 [`base`](https://rspress.rs/zh/api/config/config-basic.md#base)，未配置 `siteOrigin` 时使用 `base`

部署访问的站点 URL，例如 `https://example.com`。

sitemap 的 `<loc>` 应是包含协议和域名的绝对 URL，例如 `https://example.com/base/`。当存在 `base` 配置时，插件级 `siteUrl` 需要包含 `base` 的路径。

如果已经在 Rspress 中配置了 [`siteOrigin`](https://rspress.rs/zh/api/config/config-basic.md#siteorigin) 和 [`base`](https://rspress.rs/zh/api/config/config-basic.md#base)，可以省略插件级 `siteUrl`。完整 URL 拼接顺序是 `siteOrigin + base + routePath`。如果既没有配置插件级 `siteUrl`，也没有配置 `siteOrigin`，插件会回退使用 `base`，这会保留已有的相对路径行为，但不会生成绝对 sitemap URL：

```ts
// rspress.config.ts
import path from 'path';
import { defineConfig } from '@rspress/core';
import { pluginSitemap } from '@rspress/plugin-sitemap';

export default defineConfig({
  siteOrigin: 'https://example.com',
  base: '/base/',
  plugins: [
    // siteUrl 默认为 'https://example.com/base/'
    pluginSitemap(),
  ],
});
```

### customMaps

- **类型**：

```ts
interface Sitemap {
  loc: string;
  lastmod?: string;
  changefreq?: ChangeFreq;
  priority?: Priority;
}

interface CustomMaps {
  [routePath: string]: Sitemap;
}
```

- **默认值**：`{}`

用于给某些重要页面单独设置自定义的 sitemap 值。

### defaultChangeFreq

- **类型**：`ChangeFreq`
- **默认值**：`'monthly'`
- **可选值**：`"always" | "hourly" | "daily" | "weekly" | "monthly" | "yearly" | "never"`

> changefreq: 页面可能更改的频率。此值提供一般信息给搜索引擎，可能并不完全与它们爬取页面的频率相对应。

设置生成的 sitemap 文件中，每个页面默认的 [changefreq](https://www.sitemaps.org/protocol.html) 值。

### defaultPriority

- **类型**：`Priority`
- **默认值**：`'0.5'`
- **可选值**：`"0.0" | "0.1" | "0.2" | "0.3" | "0.4" | "0.5" | "0.6" | "0.7" | "0.8" | "0.9" | "1.0"`

> priority: 此 URL 相对于网站上其他 URL 的优先级。

设置生成的 sitemap 文件中，每个页面默认的 [priority](https://www.sitemaps.org/protocol.html) 值。