认识 Rspress:基于 Rust 驱动的站点生成器

如果你维护着一个 React 组件库或面向开发者的项目,你可能已经遇到过同样的权衡:文档工具要么快速但功能受限,要么灵活但速度慢。Rspress 的构建目标就是填补这一空白。

什么是 Rspress?

Rspress 是一个基于 Rsbuild 构建的 React 文档生成器和静态站点生成器,由 Rspack 打包器驱动——一个基于 Rust 的、与 webpack 兼容的打包器。准确地说:Rspress 本身是一个 React 框架,而不是 Rust 应用程序。性能提升来自底层 Rspack 基于 Rust 的构建工具链,而你仍然像往常一样使用 React 和 MDX 编写文档和组件。

它是更广泛的 Rstack 生态系统的一部分——一个围绕 Rspack 构建的统一 JavaScript 工具链——该生态系统还包括 Rsbuild、Rslib、Rsdoctor 和 Rstest。

Rspress 面向两个主要使用场景:开发者文档站点和组件库文档。它开箱即用地支持 MDX,这意味着你可以直接在 Markdown 页面中嵌入实时 React 组件——当你需要在文字说明旁边展示交互式示例时非常有用。

Rspress 2.0 的新特性

Rspress 2.0 于 2026 年初发布,不仅仅关注原始构建性能。以下是主要变化。

重新设计的主题系统

默认主题经过了全面的视觉改造。更重要的是,2.0 引入了四个级别的自定义:

• CSS 变量 — 调整颜色、代码块背景和布局样式
• BEM 类名 — 在不与 CSS 框架冲突的情况下覆盖组件样式
• ESM 重新导出覆盖 — 通过 theme/index.tsx 替换任何内置组件
• 组件弹出 — 使用 rspress eject [component] 将组件源代码复制到你的项目中并直接修改

这取代了 1.x 中不稳定的主题 API,为你提供了一个可预测的分层自定义路径。

使用 Shiki 进行构建时语法高亮

Rspress 2.0 用 Shiki 替换了运行时高亮,Shiki 在编译时运行。这意味着零运行时开销、通过 TextMate 语法实现准确的 VS Code 风格高亮,以及对转换器的支持,如用于内联 TypeScript 类型提示的 @rspress/plugin-twoslash。

通过懒编译实现更快的开发启动

lazyCompilation 现在默认启用。页面仅在开发期间访问时才会编译,这意味着无论你的文档站点有多大,启动都几乎是即时的。链接悬停时的路由预加载策略使导航保持流畅。

持久化缓存也默认开启,将热启动构建时间缩短 30-60%。

使用 SSG-MD 生成 AI 友好的文档

Rspress 2.0 引入了 SSG-MD(静态站点生成到 Markdown)——这个功能在标准 HTML 输出的同时,将你的文档渲染为干净的 Markdown 文件,然后生成遵循 llms.txt 规范的 llms.txt 和 llms-full.txt 文件。

import { defineConfig } from '@rspress/core';

export default defineConfig({
  llms: true,
});

与事后将 HTML 转换为 Markdown 不同,SSG-MD 在渲染期间从 React 虚拟 DOM 工作,产生更高质量的输出。你还可以使用 import.meta.env.SSG_MD 控制每个组件包含的内容。请注意,此功能仍在完善中,团队已将进一步的改进标记为路线图的一部分。

包整合

在 2.0 中,旧的 rspress、@rspress/runtime、@rspress/shared 和 @rspress/theme-default 包合并为单个 @rspress/core 包。该框架现在需要 Node.js 20+ 和 React 18 或 19。

你应该使用 Rspress 吗?

如果你正在为 React 项目或组件库构建文档,并且需要快速构建、MDX 支持和可实际自定义的主题,Rspress 是一个很好的选择。它直接与 Rslib 集成以支持组件库工作流,插件生态系统——包括 Algolia 搜索、站点地图生成和 twoslash——涵盖了大多数文档站点需求。

如果你的项目使用 Vue 或 Svelte,或者你需要更成熟的生态系统,VitePress 或 Docusaurus 仍然是可靠的替代方案。但对于 React 优先的文档,Rspress 2.0 值得仔细研究。

常见问题

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers. Check our GitHub repo and join the thousands of developers in our community.