Rspress 2.0 发布：面向体验与 AI 的全新升级

  • 2026-02-05
    北京

  • 本文字数：6989 字

    阅读完需：约 23 分钟

我们很高兴地宣布 Rspress 2.0 的正式发布！

Rspress 是基于 Rsbuild 的静态站点生成器，专为开发者打造的文档站工具。自 2023 年正式发布以来，Rspress 1.x 累计迭代 144 个版本，共有 125 位贡献者 参与项目开发。越来越多的开发者选择 Rspress，借助其高效的编译性能、约定式路由和组件库预览等功能，构建了可靠的文档站点。

根据社区的反馈和建议，Rspress 2.0 在 主题美观度、人工智能原生、文档开发体验、与 Rslib 一起使用 等方面进行了更深入的研究。

为什么是 Rspress 2.0

Rspress 1.x 已经解决了文档站框架编译性能的问题，但仍然存在一些问题影响着作为文档开发工具的核心体验。2.0 版本将不仅仅针对编译性能的追求，也侧重于文档站体验的其他方面：

  • 主题风格：一套更美观的默认主题，并提供了多种自定义主题方式，解决了 1.x 在主题定制上缺乏稳定 API 的问题；

  • AI-native：文档不仅服务于人类读者，也需要被 Agent 更好地理解和使用。Rspress 现在内置了 llms.txt 生成并从 SSG 衍生出的 SSG-MD 功能，生成高质量的 Markdown 渲染内容供 Agent 读取；

  • 双击编译，瞬间启动：默认启用 lazyCompilation，配合链接悬停时对资源的预加载功能，仅在访问特定路由时构建所需文件，无论实现项目规模大小，dev 也可瞬间启动；

  • Shiki 代码高亮：默认集成 Shiki，在构建时完成语法高亮，支持主题切换、变压器扩展，比如 @rspress/plugin-twoslash，带来更丰富的代码块展示效果；

  • 文档开发体验：优化 _nav.json、_meta.json 文件的 HMR 等并新增 json schema 用于 IDE 内的代码提示；默认开启死链检查功能；新增文件代码块语法，支持外部引用文件；@rspress/plugin-preview 和 @rspress/plugin-playground 支持同时使用等；

  • Rslib 集成：现在可以在使用 create-rslib 创建组件库项目时，选择 Rspress 作为文档工具，快速构建组件库项目站点。

这是一次对现有架构的全面升级，下面将介绍 Rspress 2.0 及其 全新主题、高质量 llms.txt 生成、集成 Shiki、后续编译等重要功能。

图片

2.0 新特性

全新主题

2.0 默认主题令人期待的一次系统性升级，它由团队设计师 @Zovn Wei 整体设计，在视觉效果和阅读体验上都有较轻的提升，并且每个组件需要独立替换，拥有非常多的可定制性。

图片

主题定制

按照定制化程度从低到高，有 CSS 变量、BEM 类名、ESM 重导出覆盖、组件弹出四种自定义主题[11]方式。

  • CSS 指标：新主题涉及了更多 CSS 指标，覆盖主题颜色、代码块、首页等样式。您可以在 CSS 指标[12] 页面进行预览并调整所有 CSS 指标，找到满意的配置后直接复制到项目中使用。

:root {  /* 自定义主题色 */  --rp-c-brand: #3451b2;  --rp-c-brand-dark: #2e4599;  /* 自定义代码块样式 */  --rp-code-block-bg: #1e1e1e;}
复制代码

  • BEM 类名：内置组件现在均采用 BEM 命名规范。这是十分之一 Old School 的选择，但也是我们深思熟虑的决定。用户可以通过 CSS 选择器精准调整样式，HTML 结构更加清晰；同时与 Rspress 用户自身使用的 CSS 框架解耦合，用户可以任意选择 CSS 框架（Tailwind [14]、Less [15]、Sass [16] 等），比如使用 Tailwind V4 或 V3 而不用担心版本，也不用担心与 Rspress 内置 CSS 产生冲突。

/* BEM 命名规范 */.rp-[component-name]__[element-name]--[modifier-name] {}/* 根据 BEM 类名轻松覆盖组件样式 */.rp-nav__title {  height: 32px;}.rp-nav-menu__item--active {  color: purple;}
复制代码

  • ESM 重导出覆盖：如果 CSS 上的修改无法满足定制需求，可以通过 JS 进行更深度的定制。在 theme/index.tsx 中使用 ESM 重导出[17]，可以覆盖任意一个 Rspress 的内置组件。

图片

  • 修改组件弹出：你可以使用全新的 `rspress pop [组件]` 命令，这个命令将指定的组件源代码复制到 theme/components/ 目录下，你可以自由这些代码，甚至直接替换 AI，来实现深度定制。

# 将 DocFooter 组件导出到 theme 目录rspress eject DocFooter
复制代码

导航栏、侧边栏标签

Rspress 2.0 实现了 Tag 组件[19]，现在可以使用 frontmatter 中的标签属性，在侧边栏或导航栏进行 UI 标注。

---tag: new, experimental # 会在 H1 和 Sidebar 进行显示---import { Tag } from '@rspress/core/theme';# Tag## Common tags <Tag tag="new" /> {/* 会在右侧 outline 进行显示 */}
复制代码

图片

内置多语言支持

在 1.x 版本中，Rspress 仅内置了中文，如果使用其他语言如 zh，必须对所有的文本都进行配置，使用起来更繁琐。现在 2.0 主题内置了 zh、en、ja、ko、ru 等多种语言的翻译文本，系统会根据语言配置自动进行“Tree Shaking”，仅限你使用到的文本及语言，未内置的语言会兜底到 en 文本。您也可以通过 `i18nSource` 配置项扩展或覆盖翻译文本。

Rspress 未来会支持更多内置语言，如果你有兴趣，请参考 这位贡献者的 Pull Request [21]。

llms.txt 支持

Rspress 现在将 llms.txt [22] 生成能力集成到 core 中，并实现了全新的 SSG-MD（Static Site Generation to Markdown，静态站点 Markdown 生成）能力。

在基于 React 动态渲染的前端框架中，往往存在静态信息无法提取的问题，Rspress 也面临同样的挑战。Rspress 用户通过 MDX 片段[23]、React 组件、Hooks 以及 TSX 路由等动态特性来增强表现力。但这些动态转换在 Markdown 文本内容时会面临以下问题：

  • 直接将 MDX 输入给 AI 会包含大量代码噪音，并丢失 React 组件内容；

  • 将 HTML 转为 Markdown 往往效果不佳，信息质量难以保证。

为了解决这个问题，Rspress 2.0 引入了 SSG-MD [24] 特性。这是一个全新的功能，它类似于 静态站点生成（SSG）[25]，但不同的地方相当于你的页面渲染为 Markdown，而不是文件 HTML 文件，并生成 llms.txt [26] 及 llms-full.txt 相关文件。

图片

相比于将 HTML 转化为 Markdown 等传统方式，SSG-MD 在渲染期间拥有更优质的信息源，比如 React 虚拟 DOM，从而保证更高的静态信息质量和灵活性。

图片

启用方式非常简单：

import { defineConfig } from '@rspress/core';export default defineConfig({  llms: true,});
复制代码

构建后将生成如下结构：

图片

若想定制自定义组件的渲染内容，可通过环境变量控制：

图片

这样既保证了文档的交互体验，也能帮助 AI 理解组件的语义信息。

参见 SSG-MD 使用指南[27]

Shiki 编译时代码块高亮

Rspress 2.0 默认使用 Shiki [28] 进行代码高亮。相比 1.x 的 prism 运行时高亮方案，Shiki 在编译时完成高亮处理。

  1. 支持多种主题样式，比如在 CSS 变量[29] 页面可以交互式切换和预览不同的 Shiki 主题。

  2. 同时 Shiki 也允许使用自定义的 变压器[30] 进行扩展来丰富的写作，例如 twoslash 等。

  3. 引入编程语言，不增加运行时间和包体积。

  4. 基于 TextMate 语法实现与 VS Code 一致的准确语法高亮。

下面是一些 Shiki Transformer 的视觉，仔细感受 Shiki 带来的文档创意：

使用 @rspress/plugin-twoslash [31]

const hi = 'Hello';const msg = `${hi}, world`;//    ^?
复制代码

使用 transformerNotationFocus [32]

console.log('Not focused');console.log('Focused'); // [!code focus]console.log('Not focused');
复制代码

参见 代码块[33]

构建性能提升

Rspress 2.0 底层由 Rsbuild 和 Rspack 2.0 预览版本驱动，同时默认开启了后续编译[34] 和 持久化存储[35]。

编译

默认开启 dev.lazyCompilation [36]，只有当你访问某些页面时，该页面才会被编译，大幅提升了开发速度启动，甚至实现了数十级的冷启动。Rspress 同时实现了路由的预加载策略，当鼠标暂停在链接上时会预先加载目标路由页面，搭配 lazyCompilation 实现稀疏的开发体验。

图片

持久化存储

2.0 默认同时开启了 持久化服务器[37]，在热启动中复用上次编译的结果，提升了 30%-60%的构建速度。这意味着在首次运行 rspress dev 或 rspress build 之后，后续启动速度都会明显提升。

文档开发体验

默认开启死链检查

Rspress 2.0 默认开启死链检查功能。在构建过程中，会自动检测文档中的无效链接，帮助你及时发现和修复。

import { defineConfig } from '@rspress/core';export default defineConfig({  markdown: {    link: {      checkDeadLinks: true, // 默认开启，可通过 false 关闭    },  },});
复制代码

图片

参见 链接[38]

文件代码块

您可以使用 file="./path/to/file" 属性来引用外部文件作为代码块的内容，将示例代码放在单独的文件中维护中。

```ts file="./_demo.ts"```
复制代码

```tsx file="<root>/src/components/Button.tsx"```
复制代码

请参阅 文件代码块[39]

预览 更灵活的元用法

@rspress/plugin-preview [40] 现在基于元属性使用，更加灵活，也可以殴打文件代码块。

下面是一个使用 iframe 预览代码块的示例：

```tsx preview="iframe-follow" file="./_demo.ts"```
复制代码

它将会渲染为：

图片

并且 @rspress/plugin-playground [41] 现在支持和 plugin-preview 一起使用，通过 meta 属性切换即可，例如 ```tsx playground

支持 HMR 的一些配置文件

基于 Rsbuild 重新设计的 虚拟模块插件[42]，现在支持 i18n.json、_nav.json、_meta.json文件代码块以及 @rspress/plugin-preview 中 iframe 相关的 HMR。修改这些配置文件后，页面会自动热更新，无需手动刷新。

Rslib 和 Rspress

在使用 create-rslib 项目项目时，您现在可以选择 Rspress 工具。这让您能够在开发组件库的同时，快速搭建搭建的文档站点，用于编写创建组件的使用说明、展示 API 参考，或实时预览组件效果。

执行 npm create rslib@latest 并选中 Rspress，会生成下方的文件结构：

├── docs│   └── index.mdx├── src│   └── Button.tsx├── package.json├── tsconfig.json├── rslib.config.ts└── rspress.config.ts
复制代码

模版中内置了 rsbuild-plugin-workspace-dev [43] 插件，可在启动 Rspress 开发服务器的同时自动运行 Rslib 的 watch 命令。

直接运行 npm run doc 启动 Rspress 的开发服务器对 Rslib 组件库进行预览：

{  "scripts": {    "dev": "rslib build --watch",    "doc": "rspress dev" // 执行该命令  }}
复制代码

更多 Rspress 官方插件

Rspress 2.0 新增了多个官方插件：

  • @rspress/plugin-algolia：支持替换 Rspress 的内置搜索为 Algolia DocSearch （感谢 @algolia 团队的帮助）；

  • @rspress/plugin-twoslash：为 TypeScript 代码块添加类型提示；

  • @rspress/plugin-llms：为不支持 SSG 和 SSG-MD 的项目提供 llms.txt 生成能力；

  • @rspress/plugin-sitemap：自动生成 Sitemap 文件，用于优化 SEO。

其他重大变化

从 Rspress 1.x 迁移

如果您是 1.x 项目的用户，我们准备了一份升级的迁移文档，帮助您从 1.x 升级到 2.0。

你可以直接使用 Pages 中的“复制 Markdown”功能，将其输入给你常用的编码代理（如 Claude Code 等）来完成迁移。

请参考 迁移指南[51]。

删除 mdxRs 配置

我们注意到很大一部分 1.x 用户为了使用 Shiki、组件库预览功能和自定义评论/rehype 插件，而主动关闭 mdxRs，并且在开启循环编译和持久化缓存后，即使使用 JS 版本的 mdx 解析器，性能优化效果已经非常显着。

为了换取更好的扩展性和可维护性，我们决定在 Markdown/MDX 编译流程中不再使用 Rust 版本的 MDX 解析器（@rspress/mdx-rs）。这使得 Rspress 能够更好地集成 Shiki 等 JavaScript 生态的工具。

Node.js 与下游依赖版本要求

Rspress 2.0 要求 Node.js 版本 20+，React 版本 18+。

包名及导入路径变更

Rspress 将 rspress、、、@rspress/runtime都 整合进了 中，项目@rspress/shared和 插件现在只需安装一个包即可。@rspress/theme-default@rspress/core@rspress/core

{  "dependencies": {-   "rspress": "1.x"-   "@rspress/shared": "1.x"+   "@rspress/core": "^2.0.0"  }}
复制代码

- import { defineConfig } from 'rspress/config';+ import { defineConfig } from '@rspress/core';
复制代码

- import { useDark } from 'rspress/runtime'- import { PackageManagerTabs } from 'rspress/theme';+ import { useDark } from '@rspress/core/runtime'+ import { PackageManagerTabs } from '@rspress/core/theme';
复制代码

如果你开发了 Rspress 插件，那么该插件的 peerDependency 从 rspress 更改为 @rspress/core：

{  "peerDependencies": {    "@rspress/core": "^2.0.0"  }}
复制代码

下一步

Rspress 2.0 的发布只是一个新的起点。本次发布后，Rspress 将持续迭代：

  • 推进生态集成：与 Rslib、Rstest 更深度地结合，提供接入组件项目和库项目的标准化开发体验；

  • 探索 AI 与文档更复杂的集成：如智能问答、自动摘要等；完善 SSG-MD 决策并更加自动化。

感谢所有为 Rspress 做出贡献的开发者和用户！如果您在使用过程中遇到问题或有任何建议，欢迎在 GitHub Issues [52] 中反馈。

立即使用或升级到 Rspress 2.0，体验全新的文档开发之旅！

npm create rspress@latest
复制代码

博客原文链接：https://rspress.rs/zh/blog/rspress-v2

参考资料

[1] Rsbuild：https://rsbuild.rs/

[2] 自定义主题： https://v2.rspress.rs/zh/guide/basic/custom-theme

[3] llms.txt：  https://llmstxt.org/

[4] SSG-MD：  https://v2.rspress.rs/zh/guide/basic/ssg-md

[5] 懒加载编译：  https://rspack.rs/guide/features/lazy-compilation

[6] @rspress/plugin-twoslash:  https://v2.rspress.rs/zh/plugin/official-plugins/twoslash

[7] json 模式：  https://v2.rspress.rs/zh/guide/basic/auto-nav-sidebar #json -schema-type 提示

[8] @rspress/plugin-preview:  https://v2.rspress.rs/zh/plugin/official-plugins/preview

[9] @rspress/plugin-playground：  https://rspress.rs/plugin/official-plugins/playground

[10] @Zovn 魏：  https://x.com/wei_zhong41532

[11] 自定义主题：  https://v2.rspress.rs/zh/guide/basic/custom-theme

[12] CSS 变量：  https://v2.rspress.rs/zh/ui/vars

[13] BEM 命名规范：  https://getbem.com/

[14] Tailwind：  https://tailwindcss.com/

[15] Less：  https://lesscss.org/

[16] Sass：  https ://sass-lang.com/

[17] ESM 重新导出：  https://v2.rspress.rs/zh/guide/basic/custom-theme #reexport

[18] rspress eject [component]:  https://v2.rspress.rs/zh/api/commands #rspress -eject

[19] 标签组件：  https://v2.rspress.rs/zh/ui/layout-components/tag

[20] i18nSource：  https://v2.rspress.rs/zh/api/config/config-basic #i18nsource

[21] 贡献者的 Pull 请求：  https://github.com/web-infra-dev/rspress/pull/2827

[22] llms.txt：  https://llmstxt.org/

[23] MDX 片段：  https://v2.rspress.rs/zh/guide/use-mdx/components

[24] SSG-MD：  https://v2.rspress.rs/zh/guide/basic/ssg-md

[25] 静态站点生成（SSG）：  https://v2.rspress.rs/zh/guide/basic/ssg

[26] llms.txt：  https://llmstxt.org/

[27] SSG-MD 使用指南：  https://v2.rspress.rs/zh/guide/basic/ssg-md

[28] Shiki：  https://shiki.style/

[29] CSS 变量：  https://v2.rspress.rs/zh/ui/vars

[30] 变形金刚：  https://shiki.style/guide/transformers

[31] @rspress/plugin-twoslash:  https://v2.rspress.rs/zh/plugin/official-plugins/twoslash

[32] transformerNotationFocus：  https://v2.rspress.rs/zh/guide/use-mdx/code-blocks #transformernotationfocus

[33] 代码块：  https: //v2.rspress.rs/zh/guide/use-mdx/code-blocks #shiki -transformers

[34] 编译：  https://rspack.rs/zh/guide/features/lazy-compilation

[35] 持久化服务器：  https://rsbuild.rs/zh/config/performance/build-cache

[36] dev.lazyCompilation：  https://rsbuild.rs/zh/config/dev/lazy-compilation

[37] 持久化服务器：  https://rsbuild.rs/zh/config/performance/build-cache

[38] 链接：  https ://v2.rspress.rs/zh/guide/use-mdx/link

[39] 文件代码块：  https: //v2.rspress.rs/zh/guide/use-mdx/code-blocks #file -code-block

[40] @rspress/plugin-preview:  https://v2.rspress.rs/zh/plugin/official-plugins/preview

[41] @rspress/plugin-playground:  https://v2.rspress.rs/zh/plugin/official-plugins/playground

[42] 虚拟插件模块：  https://github.com/rstackjs/rsbuild-plugin-virtual-module

[43] rsbuild-plugin-workspace-dev：  https://github.com/rstackjs/rsbuild-plugin-workspace-dev

[44] @rspress/plugin-algolia：  https://v2.rspress.rs/zh/plugin/official-plugins/algolia

[45] Algolia DocSearch：  https://docsearch.algolia.com/

[46] @algolia：  https://x.com/algolia

[47] @rspress/plugin-twoslash：  https://v2.rspress.rs/zh/plugin/official-plugins/twoslash

[48] @rspress/plugin-llms：  https://v2.rspress.rs/zh/plugin/official-plugins/llms

[49] @rspress/plugin-sitemap：  https://v2.rspress.rs/zh/plugin/official-plugins/sitemap

[50] 网站地图：  https://www.sitemaps.org

[51] 迁移指南：  https://v2.rspress.rs/zh/guide/migration/rspress-1-x

[52] GitHub Issues：  https://github.com/web-infra-dev/rspress/issues

Copyright © 2026, Geekbang Technology Ltd. All rights reserved. 极客邦控股（北京）有限公司 | 京 ICP 备 16027448 号 - 5京公网安备京公网安备 11010502039052号 | 产品资质