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

# 构建配置

## builderConfig

- **类型**: `RsbuildConfig`

用于自定义 Rsbuild 的配置项，完整配置项请查看 [Rsbuild - 配置](https://rsbuild.rs/zh/config/)。

- 示例：使用 [resolve.alias](https://rsbuild.rs/zh/config/resolve/alias) 配置路径别名：

```ts title="rspress.config.ts"
export default defineConfig({
  builderConfig: {
    resolve: {
      alias: {
        '@common': './src/common',
      },
    },
  },
});
```

- 示例：使用 [tools.rspack](https://rsbuild.rs/zh/config/tools/rspack) 修改 Rspack 配置，比如注册一个 webpack 或 Rspack 插件。比如：

```ts title="rspress.config.ts"
export default defineConfig({
  builderConfig: {
    tools: {
      rspack: async config => {
        const { default: ESLintPlugin } = await import('eslint-webpack-plugin');
        config.plugins?.push(new ESLintPlugin());
        return config;
      },
    },
  },
});
```

::: warning

如果你想要修改产物输出目录，请使用 [outDir](https://rspress.rs/zh/api/config/config-basic.md#outdir)。

:::

## builderConfig.plugins

- **类型**: `RsbuildPlugin[]`

用于注册 [Rsbuild 插件](https://rsbuild.rs/zh/plugins/list/)。

你可以利用 Rsbuild 丰富的插件生态来增强和扩展构建能力。

- 示例：通过 [@rsbuild/plugin-vue](https://rsbuild.rs/plugins/list/plugin-vue) 支持 Vue SFC。

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';
import { pluginVue } from '@rsbuild/plugin-vue';

export default defineConfig({
  builderConfig: {
    plugins: [pluginVue()],
  },
});
```

- 示例：通过 [rsbuild-plugin-google-analytics](https://github.com/rstackjs/rsbuild-plugin-google-analytics) 添加 Google analytics。

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';
import { pluginGoogleAnalytics } from 'rsbuild-plugin-google-analytics';

export default defineConfig({
  builderConfig: {
    plugins: [
      pluginGoogleAnalytics({
        // replace this with your Google tag ID
        id: 'G-xxxxxxxxxx',
      }),
    ],
  },
});
```

- 示例：通过 [rsbuild-plugin-open-graph](https://github.com/rstackjs/rsbuild-plugin-open-graph) 添加 Open Graph meta 标签。

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';
import { pluginOpenGraph } from 'rsbuild-plugin-open-graph';

export default defineConfig({
  builderConfig: {
    plugins: [
      pluginOpenGraph({
        title: 'My Website',
        type: 'website',
        // ...options
      }),
    ],
  },
});
```

你也可以覆盖内置的 [@rsbuild/plugin-react](https://rsbuild.rs/zh/plugins/list/plugin-react) 并自定义插件的选项。

比如：

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';
import { pluginReact } from '@rsbuild/plugin-react';

export default defineConfig({
  builderConfig: {
    plugins: [
      pluginReact({
        // ...options
      }),
    ],
  },
});
```

### 默认配置

如果你需要查看默认的 Rspack 或 Rsbuild 配置，可以在执行 `rspress dev` 或 `rspress build` 命令时，添加 `DEBUG=rsbuild` 参数：

```bash
DEBUG=rsbuild rspress dev
```

在执行后，`doc_build` 目录下会生成 `rsbuild.config.js` 文件，里面包含了完整的 `builderConfig`。

> 请查看 [Rsbuild - 调试模式](https://rsbuild.rs/zh/guide/debug/debug-mode) 来了解更多调试 Rsbuild 的方法。

## markdown

配置 MDX 相关的编译能力。

### markdown.remarkPlugins

- **类型**: `Array`
- **默认值**: `[]`

用于增加一些自定义 remark 插件。比如：

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';
import remarkAutolinkHeadings from 'remark-autolink-headings';

export default defineConfig({
  markdown: {
    remarkPlugins: [
      [
        remarkAutolinkHeadings,
        {
          behavior: 'wrap',
        },
      ],
    ],
  },
});
```

### markdown.rehypePlugins

- **类型**: `Array`

用于增加一些自定义的 rehype 插件。比如：

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';
import rehypeAutoLinkHeadings from 'rehype-autolink-headings';

export default defineConfig({
  markdown: {
    rehypePlugins: [
      [
        rehypeAutoLinkHeadings,
        {
          behavior: 'wrap',
        },
      ],
    ],
  },
});
```

### markdown.shiki

- **类型**: `import('@shikijs/rehype').RehypeShikiOptions`

- **默认值**:

```ts
const cssVariablesTheme = createCssVariablesTheme({
  name: 'css-variables',
  variablePrefix: '--shiki-',
  variableDefaults: {},
  fontStyle: true,
});
const shikiOptions = {
  theme: cssVariablesTheme,
  defaultLanguage: 'txt',
  lazy: true,
  langs: ['tsx', 'ts', 'js'],
  addLanguageClass: true,
};
```

配置 Shiki 相关配置。具体可见 [RehypeShikiOptions](https://github.com/shikijs/shiki/blob/main/packages/rehype/src/types.ts)。

### markdown.link

- **类型**:

```ts
export type RemarkLinkOptions = {
  checkDeadLinks?:
    boolean | { excludes: string[] | ((url: string) => boolean) };
  checkAnchors?: boolean | { excludes: string[] | ((url: string) => boolean) };
  autoPrefix?: boolean;
};
```

- **默认值**: `{ checkDeadLinks: true, checkAnchors: false, autoPrefix: true }`

配置链接相关的配置。

#### markdown.link.checkDeadLinks

- **类型**: `boolean | { excludes: string[] | ((url: string) => boolean) }`
- **默认值**: `true`

开启这个配置后，会基于约定式路由对文档中的链接进行检查，若出现无法访问的链接，构建会抛出错误并退出。

如果存在误判链接的情况，可以通过 `excludes` 配置忽略该错误：

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

export default defineConfig({
  markdown: {
    link: {
      checkDeadLinks: {
        excludes: ['/guide/getting-started', '/llms.txt'],
      },
    },
  },
});
```

#### markdown.link.checkAnchors

- **类型**: `boolean | { excludes: string[] | ((url: string) => boolean) }`
- **默认值**: `false`

:::info
`checkAnchors` 当前默认关闭，未来版本会将默认值设置为 `true`。
:::

开启这个配置后，Rspress 会检查站内链接中的锚点是否存在于目标 Markdown 或 MDX 页面中。它会检查当前页面锚点、相对路径链接和绝对路径链接，但会跳过外部 URL 中的锚点。

如果存在误判锚点的情况，可以通过 `excludes` 配置忽略该错误：

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

export default defineConfig({
  markdown: {
    link: {
      checkAnchors: {
        excludes: ['/guide/getting-started#custom-anchor'],
      },
    },
  },
});
```

#### markdown.link.autoPrefix

- **类型**: `boolean`
- **默认值**: `true`

开启这个配置后，会基于约定式路由对文档中的链接自动增加关于 [国际化](https://rspress.rs/zh/guide/basic/i18n.md) 和 [多版本](https://rspress.rs/zh/guide/basic/multi-version.md) 前缀。

比如，用户在 `docs/zh/guide/index.md` 中写了一个链接 `[](/guide/getting-started)`，Rspress 会自动将其转换为 `[](/zh/guide/getting-started)`。

### markdown.image

- **类型**:

```ts
export type RemarkImageOptions = {
  checkDeadImages?:
    boolean | { excludes: string[] | ((url: string) => boolean) };
};
```

- **默认值**: `{ checkDeadImages: true }`

配置图片相关选项。

#### markdown.image.checkDeadImages

- **类型**: `boolean | { excludes: string[] | ((url: string) => boolean) }`
- **默认值**: `true`

开启该配置后，Rspress 会检查文档中的本地图片。如果图片引用了不存在的文件，构建会抛出错误并退出。

对于相对图片路径（例如 `./image.png`），Rspress 会相对于当前文档解析文件；对于绝对图片路径（例如 `/image.png`），Rspress 会从 `public` 目录下解析文件。

如果某些图片被误判，可以通过 `excludes` 配置忽略这些错误：

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

export default defineConfig({
  markdown: {
    image: {
      checkDeadImages: {
        excludes: ['/generated-diagram.png'],
      },
    },
  },
});
```

### markdown.showLineNumbers

- **类型**: `boolean`

是否显示代码块的行号。默认为 `false`。

全局启用后，可以在代码块 meta 中使用 `lineNumbers=false` 来为特定代码块禁用行号。反之，全局未启用时，可以使用 `lineNumbers` 或 `lineNumbers=true` 来为特定代码块启用行号。详见[显示代码行号](https://rspress.rs/zh/guide/use-mdx/code-blocks.md#%E6%98%BE%E7%A4%BA%E4%BB%A3%E7%A0%81%E8%A1%8C%E5%8F%B7)。

### markdown.defaultWrapCode

- **类型**: `boolean`

是否默认启用长代码换行展示。默认为 `false`。

全局启用后，可以在代码块 meta 中使用 `wrapCode=false` 来为特定代码块禁用换行。反之，全局未启用时，可以使用 `wrapCode` 或 `wrapCode=true` 来为特定代码块启用换行。详见[代码换行](https://rspress.rs/zh/guide/use-mdx/code-blocks.md#%E4%BB%A3%E7%A0%81%E6%8D%A2%E8%A1%8C)。

### markdown.defaultCodeOverflow

- **类型**: `{ height?: number; behavior?: 'fold' | 'scroll' }`

默认情况下，Rspress 的代码块会完全展开显示，没有 overflow 行为。你可以通过 ` ```tsx fold ` 等 meta 属性控制单个代码块的 overflow 行为。此配置项可以为所有代码块设置全局默认的 overflow 行为，超过指定高度时自动应用。

- `height`：高度阈值，单位为像素。未设置时不应用任何 overflow 行为。
- `behavior`：超出高度时的处理方式，默认为 `'scroll'`。
  - `'scroll'`：固定高度，显示垂直滚动条。
  - `'fold'`：可折叠，显示展开/收起按钮。

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

export default defineConfig({
  markdown: {
    defaultCodeOverflow: {
      height: 400,
      behavior: 'fold',
    },
  },
});
```

单个代码块可通过 `height` 或 `fold` meta 属性覆盖默认行为。详见[代码块高度](https://rspress.rs/zh/guide/use-mdx/code-blocks.md#%E4%BB%A3%E7%A0%81%E5%9D%97%E9%AB%98%E5%BA%A6)。

### markdown.crossCompilerCache

- **类型**: `boolean`
- **默认值**: `true`

是否在 `rspress build` 时启用跨编译器缓存。启用后，Rspress 会在多个编译器（web 和 node）之间缓存 MDX 解析结果，从而加速生产环境构建，构建时间可减少约 10%。

该选项仅在生产环境构建时生效，灵感来自 [Docusaurus](https://docusaurus.io/)。

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

export default defineConfig({
  markdown: {
    crossCompilerCache: true,
  },
});
```

### markdown.globalComponents

- **类型**: `string[]`

注册全局组件，无需 import 语句，就可以在每个 MDX 文件中使用。比如：

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';
import path from 'path';

export default defineConfig({
  markdown: {
    globalComponents: [path.join(__dirname, 'src/src/components/Alert.tsx')],
  },
});
```

这样你就可以在 MDX 文件中使用 `Alert` 组件了：

```mdx title="test.mdx"
<Alert type="info">This is a info alert</Alert>
```

### markdown.extractDescription

- **类型**: `boolean`
- **默认值**: `true`

是否自动从 Markdown 内容中提取描述。启用后，Rspress 会提取 `h1` 标题下方第一段有内容的段落作为页面描述。如果在 [frontmatter](https://rspress.rs/zh/api/config/config-frontmatter.md#description) 中指定了 `description`，则优先使用，跳过自动提取。

提取的描述用于 `<meta name="description">` 和 Open Graph 的 `<meta property="og:description">` 标签。详情请参阅[自定义 Head 标签 - description 的获取方式](https://rspress.rs/zh/guide/advanced/custom-head.md#description-%E7%9A%84%E8%8E%B7%E5%8F%96%E6%96%B9%E5%BC%8F)。

### markdown.cjkFriendlyEmphasis

- **类型**: `boolean`
- **默认值**: `true`

是否启用对 CJK（中日韩）友好的强调和删除线解析。启用后，即使标记内部含有标点符号（CJK 或 ASCII），只要标记外侧紧邻 CJK 字符，`**`、`*` 和 `~~` 也能正确解析为强调或删除线。

此选项解决了 [CommonMark 规范的一个限制](https://github.com/commonmark/commonmark-spec/issues/650)，该限制导致强调标记在 CJK 字符相邻时无法正常工作。例如，未启用此选项时 `**该星号不会被识别，而是直接显示。**这是因为它没有被识别为强调符号。` 中的第一句不会被渲染为粗体，因为闭合 `**` 后紧跟着 CJK 字符。有关此扩展的更多详情，请参见 [markdown-cjk-friendly](https://github.com/tats-u/markdown-cjk-friendly)。

默认启用。如需禁用：

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

export default defineConfig({
  markdown: {
    cjkFriendlyEmphasis: false,
  },
});
```