基础配置
root
- 类型：
string - 默认值：
docs
指定文档根目录。比如：
该配置同时支持相对路径和绝对路径，相对路径相对于当前工作目录。
当然，除了通过配置文件来指定文档根目录，你也可以通过命令行参数来指定，比如：
base
- 类型：
string - 默认值：
/
部署基础路径。比如，如果你计划将你的站点部署到 https://foo.github.io/bar/，那么你应该将 base 设置为 "/bar/"：
siteOrigin
- 类型：
string - 默认值：
""
站点的可选部署 origin，例如 https://foo.github.io。
Rspress 在生成需要绝对 URL 的文件时会结合该值和 base，例如 sitemap.xml、llms.txt 链接或插件输出。完整 URL 拼接顺序是 siteOrigin + base + routePath。
如果没有配置 siteOrigin，Rspress 会回退使用 base + routePath。
如果你的站点部署到 https://foo.github.io/bar/，请将 siteOrigin 设置为 "https://foo.github.io"，并将 base 设置为 "/bar/"：
title
- 类型：
string - 默认值：
"Rspress"
站点标题。这个参数将被用作 HTML 页面的标题。例如：
description
- 类型：
string - 默认值：
""
站点描述。这将用作 HTML 页面的描述。例如：
icon
- 类型：
string | URL - 默认值：
""
站点图标。这个路径将用作 HTML 页面的图标路径。例如：
对于普通路径，Rspress 会在 public 目录中找到你的图标，当然你也可以设置成一个 CDN 地址，或使用 file:// 协议或 URL 来使用本地文件绝对路径。
lang
- 类型：
string - 默认值：
"en"
站点默认使用的语言。查看 国际化 了解更多。
locales
- 类型：
Locale[] - 默认值：
undefined
配置站点支持的语言，以及各语言的站点信息。
将顶层的 lang 设为其中一个语言代码，指定站点的默认语言。Rspress 会去掉默认语言路由中的语言前缀。
例如：
完整配置流程请参考国际化。如需按语言配置 nav、sidebar 等主题选项，请参考 themeConfig.locales。
i18nSourcePath
- 类型：
string - 默认值：
path.join(cwd, 'i18n.json')
指定国际化文案数据源文件的路径。默认情况下，Rspress 从当前工作目录下的 i18n.json 读取。例如：
效果与在项目根目录放置 i18n.json 文件一致。如果同时配置了 i18nSource，i18nSource 的数据将会合并并覆盖 i18nSourcePath 加载的数据。
i18nSource
- 类型：
Record<string, Record<string, string>> | ((value: Record<string, Record<string, string>>) => Record<string, Record<string, string>> | Promise<Record<string, Record<string, string>>>) - 默认值：
{}
你可以通过这个配置项来修改 Rspress 内置的国际化文案或扩展自定义组件的文案。当扩展文案时，通常配合 useI18n 一起使用。
与 i18n.json 的实现和效果均一致，任选一个使用即可，i18nSource 比 i18n.json 的优先级高，并且支持函数。
参数 i18nSource 是一个对象，其结构为：
其中第一层的 textKey 是文案的键名，第二层的 locale 是语言代码（如 zh、en），值是对应语言的翻译文本。
下面是一个修改 Rspress 内置国际化文案的示例：
i18nSource 也可以是一个函数，例如：
以下是 Rspress 内置的国际化文案：
logo
- 类型：
string | { dark: string; light: string; width?: number; height?: number } - 默认值：
""
站点 logo。这个路径将用作导航栏左上角的 logo。对象形式可选提供 width 和 height（单位为像素）作为两张图片的固有尺寸；请填写源图片的实际尺寸，以预留宽高比并减少布局偏移。例如：
Rspress 会在 public 目录中找到你的图标，当然你也可以设置成一个 CDN 地址。
当然你可以针对浅色/暗黑模式设置不同的 logo：
logoHref
- 类型：
string - 默认值：
/${lang}/
自定义 logo 的链接。默认情况下点击 logo 会跳转到当前语言的首页。例如：
logoText
- 类型：
string - 默认值：
""
站点 logo 文字。这个文字将用作导航栏左上角的 logo 文字。例如：
outDir
- 类型：
string - 默认值：
doc_build
自定义构建站点的输出目录。比如:
themeDir
- 类型：
string - 默认值：
theme
指定自定义主题目录。默认情况下，Rspress 使用当前工作目录下的 theme 目录作为自定义主题目录。你可以通过 themeDir 来自定义它。例如：
该配置同时支持相对路径和绝对路径，相对路径相对于当前工作目录。
更多关于自定义主题的内容，请参阅 自定义主题。
head
- 类型：
string|[string, Record<string, string>]|(route) => string | [string, Record<string, string>] | undefined - 也可以通过 frontmatter 针对每个页面设置
用于设置生产模式下页面 HTML 的 <head> 标签中呈现的附加元素。
globalStyles
- 类型：
string - 默认值：
undefined
用于添加全局样式，配置为样式文件的路径。例如：
sitemap
- 类型：
boolean | SitemapOptions - 默认值：
true
在生产构建时向输出目录生成 sitemap.xml。此功能已内置于 Rspress，无需安装插件，在 ssg: false 时也可使用。从 public 目录复制的已有 sitemap 文件会保留。生成的 URL 遵循 route.cleanUrls。
配置 siteOrigin 可让 sitemap 包含绝对 URL。Rspress 会将 siteOrigin、base 和每个页面的路由路径拼接起来：
设置 sitemap: false 可关闭生成，也可以传入选项对象进行自定义：
选项类型如下，可从 @rspress/core 导入 SitemapOptions：
sitemap.siteUrl
- 类型：
string - 默认值：
siteOrigin+base，未配置siteOrigin时使用base
覆盖 sitemap 条目使用的部署 URL。请使用包含基础路径的绝对 URL，例如 https://example.com/docs/。此值优先于 siteOrigin 和 base。仅支持不含查询参数和片段的 HTTP(S) URL。
如果既没有配置 sitemap.siteUrl，也没有配置 siteOrigin，条目会使用 base + routePath，保留为相对路径。配置其中任意一项即可生成绝对 sitemap URL。
sitemap.customMaps
- 类型：
Record<string, Sitemap> - 默认值：
{}
覆盖指定页面的 sitemap 值。键为不含 base 的路由路径，值会覆盖生成的 loc、lastmod、changefreq 和 priority。lastmod 默认使用源文件的修改时间。此选项用于自定义已有页面，不会添加路由。
sitemap.defaultChangeFreq
- 类型：
ChangeFreq - 默认值：
'monthly'
每个页面默认的 changefreq 值。可选值为 'always'、'hourly'、'daily'、'weekly'、'monthly'、'yearly' 和 'never'。可通过 customMaps 为指定页面覆盖此值。
sitemap.defaultPriority
- 类型：
Priority - 默认值：
'0.5'
每个页面默认的 priority 值，可选值从 '0.0' 到 '1.0'，间隔为 0.1。根路由 / 使用 '1.0'。可通过 customMaps 为指定页面覆盖此值。
mediumZoom
- 类型：
boolean|{ selector?: string } - 默认值：
true
是否开启图片放大功能。默认开启，你可以通过设置 mediumZoom 为 false 来关闭。
底层使用的是 medium-zoom 库来实现的。
使用示例：
search
- 类型：
如果需要从搜索索引中排除某个页面，可以在该页面的 front matter 中设置 search: false。
searchHooks
- 类型：
string - 默认值：
undefined
你可以通过 searchHooks 参数来增加搜索运行时钩子逻辑，比如：
关于具体的钩子逻辑，你可以阅读 自定义搜索功能。
versioned
- 类型：
boolean - 默认值：
true
配置 multiVersion 后，默认会为每个版本创建独立的搜索索引，使搜索结果仅包含用户当前所选版本的页面。将 versioned 设为 false 可以关闭该行为，搜索结果将包含所有版本的文档。
codeBlocks
- 类型：
boolean - 默认值：
true
是否在搜索的索引中包含代码块的内容，这可以让用户搜索代码块。
globalUIComponents
- 类型：
(string | object)[] - 默认值：
[]
你可以通过 globalUIComponents 参数来增加全局 UI 组件，比如：
globalUIComponents 的每一项可以是一个字符串，代表组件的文件路径；也可以是一个数组，第一项为组件的文件路径，第二项为组件的 props 对象，比如：
当你注册了全局组件之后，Rspress 会自动将这些 React 组件在主题中进行渲染，而不用你手动引入。
通过全局组件，你可以完成诸多自定义的功能，比如:
这样，在主题页面中会渲染组件的内容，比如添加回到顶部按钮。
同时，你也可以通过全局组件来注册全局副作用。比如：
这样，在主题页面中会执行组件的副作用。比如以下的一些需要副作用的场景:
- 针对某些页面路由进行重定向操作。
- 对页面的 img 标签进行事件监听，实现图片放大功能。
- 路由变化时，上报不同页面的 PV 数据。
- ......
multiVersion
- 类型：
{ default: string; versions: string[] }
你可以通过 multiVersion 参数来增加多版本文档支持，比如：
其中，default 为默认版本，versions 为所有版本列表。
route
- 类型：
Object
自定义路由配置。
route.include
- 类型：
string[] - 默认值：
[]
在路由中添加一些额外的文件。默认情况下，只有文档根目录中的文件才会包含在路由中。如果你想在路由中添加一些额外的文件，你可以使用这个选项。例如：
注意：数组中的字符串支持 glob 模式，填写的 glob 表达式应基于文档的
root目录，并带上对应的 extensions 后缀。
我们更加推荐在自定义 Rspress 插件中使用 addPages hook 来在路由中添加一些额外的文件，这样可以更灵活且更合理地指定页面路由和文件路径/内容。
route.exclude
- 类型：
string[] - 默认值：
[]
从路由中排除一些文件。例如：
注意：数组中的字符串支持 glob 模式，填写的 glob 表达式应基于文档的
root目录。
route.excludeConvention
- 类型：
string[] - 默认值：
['**/_[^_]*']
为方便用户在 docs 目录 中使用组件，而设置的 路由约定，默认排除以 _ 开头的文件。
如果你确实需要一些 _ 开头的路由时，你可以调整这个规则，例如设置为以 _fragment- 开头才会被排除：
route.extensions
- 类型：
string[] - 默认值：
['.js', '.jsx', '.ts', '.tsx', '.md', '.mdx']
将包含在路由中的文件的扩展名。默认情况下，Rspress 会在路由中包含所有 `'js'、'jsx'、'ts'、'tsx'、'md'、'mdx' 文件。如果你想自定义扩展名，你可以使用这个选项。例如：
route.cleanUrls
- 类型：
boolean - 默认值：
true（在 v2.1.0 之前是false）
开启后可以生成无 .html 后缀的链接，URL 可以更加简洁。设置为 false 可以保留 .html 后缀。
启用此选项可能需要在托管平台上进行额外配置。要使其生效，服务器必须能够在访问 /foo 时不经过重定向直接提供 /foo.html。
route.cleanUrlsRedirect
- 类型：
boolean - 默认值：
true
开启后，Rspress 会在客户端启动阶段以实际匹配到的路由为准，规范化浏览器地址栏中的
非规范 URL。目标格式遵循 route.cleanUrls。
route.cleanUrls 控制生成链接所使用的首选 URL 格式，
route.cleanUrlsRedirect 仅负责规范化浏览器地址栏。
该配置会在请求页面的 HTML 和客户端运行时代码加载后执行。它使用
history.replaceState，不会返回 HTTP 301/308 响应，因此无法完全替代服务端或
CDN 的 canonical 重定向，尤其不能提供相同的 SEO 效果。托管平台仍需为当前 URL
变体返回正确的 Rspress 页面；如果条件允许，建议优先配置服务端重定向。
cleanUrls: true
普通页面路由不保留 trailing slash，目录首页路由则会保留。
cleanUrls: false
普通页面路由使用 .html，目录首页路由使用 /index.html。
例如，/zh/guide/start/introduction.html 和
/zh/guide/start/introduction/index.html 都会匹配
/zh/guide/start/introduction，最终 URL 会遵循 cleanUrls 配置，并保留语言前缀。
Canonical URL 格式与 Cloudflare 的 HTML handling 保持一致，但 Cloudflare 执行的是服务端 HTTP 重定向，本配置只会在浏览器中更新 URL。
将 cleanUrlsRedirect 设置为 false 可以关闭浏览器 URL 规范化：
route.localeRedirect
- 类型：
'auto' | 'never' | 'only-default-lang' - 默认值：
'auto'
控制如何根据 window.navigator.language 将首次访问的用户重定向到最匹配的已配置语言：
auto：从任意语言重定向到最匹配的已配置语言。never：禁用自动语言重定向。only-default-lang：仅在访问默认语言时重定向。
该选项在浏览器端执行重定向。生产环境中，如果条件允许，更推荐在服务器或 CDN 边缘完成语言协商与重定向。这样可以在 HTML 下发前完成跳转，并且不依赖客户端 JavaScript。
route.useTransitions
- 类型：
boolean - 默认值：
true
启用针对 Rspress 默认 Link 组件的并发优化路由。它覆盖 Markdown 和 MDX 内容中的链接，也覆盖侧边栏项等默认主题导航链接。
默认情况下，该选项开启。除非你显式将 useTransitions 设置为 false，否则内部页面跳转都会被包裹在 React 的 startTransition 中。这可以避免新页面内容的重渲染阻塞用户输入，使页面在导航过程中保持响应和可交互。
route.prefetchLink
- 类型：
boolean - 默认值：
true
默认情况下，Rspress 的 Link 组件会在用户 hover 链接时，预请求对应内部路由的资源；在 touch 设备上也会触发同样的行为。这是一个性能优化手段。将该配置设置为 false 可禁用这一行为。
在开发环境下，链接预取会和 Rspress 默认开启的 dev.lazyCompilation 配合使用。按需编译让页面只在被访问时才编译，从而提升启动速度；链接预取则会在 hover 时提前启动目标路由编译，减少首次打开目标路由时的等待。
示例：
ssg
- 类型：
boolean | { experimentalWorker?: boolean; experimentalLoose?: boolean; } - 默认值：
true
是否在构建时将页面内容预渲染为 HTML。Rspress 默认开启 SSG。
设置 ssg: false 后会生成用于客户端渲染的 HTML 空壳。
experimentalWorker
- 类型：
boolean - 默认值：
false
开启后可以使用 Worker 来加速 SSG 过程并降低内存占用，适合大型文档站点，底层基于 tinypool。
experimentalExcludeRoutePaths
- 类型：
(string | RegExp)[] - 默认值：
[]
开启后一部分页面将不进行 SSG 渲染，直接使用 CSR 下的 html，适合用于大型文档站点绕过一小部分页面的 SSG 错误，不建议主动开启。
此选项仅影响 SSG，不会将页面排除在 SSG-MD 之外。如果被排除的页面不兼容 SSR，需要修复兼容性问题，或设置 llms: false 关闭 SSG-MD。
replaceRules
- 类型：
{ search: string | RegExp; replace: string; }[] - 默认值：
[]
你可以通过 replaceRules 来对整个站点设置文本替换规则，规则会作用于包括 _meta.json 文件、frontmatter 配置以及文档内容和标题等所有内容。
languageParity
- 类型：
Object
对文档根目录的 md 和 mdx 文件进行扫描，检测是否存在某些语言版本缺失的情况，保证语言一致性。
languageParity.enabled
- 类型：
boolean - 默认值：
false
是否启用语言一致性检查。
languageParity.include
- 类型：
string[] - 默认值：
[]
需要检查的文件夹，默认为文档根目录下所有文件。填写路径时，相对于文档各语言目录。例如：
languageParity.exclude
- 类型：
string[] - 默认值：
[]
从文档目录排除一些文件夹和文件，不进行检查。