Rspress 基于 Rspack 的文档站生成器技术调研

Rspress 是字节跳动开源的、基于 Rspack 的静态文档站生成器，定位为 VitePress 的同类方案，强调极速构建、中文文档体验和对 React/Vue 双栈内容的支持。适合需要快速构建工具文档、调试指南和组件说明的中文技术团队。

一、 基本信息

二、 技术定位与简介

Rspress 特点：

• Rspack 构建：比 Webpack 更快的生产构建。
• Markdown 优先：类似 VitePress 写作体验。
• 插件系统：搜索、图片、RSS、Twoslash 等。
• 多框架 Demo：支持在文档中嵌入 React/Vue 组件。
• 中文友好：文档、示例、社区以中文为主。

在调试工具文档场景，适合快速发布 08-开发调试工具 类结构化资源库静态站。

三、 快速上手安装说明

1. 初始化

pnpm create rspress@latest

2. 目录结构

docs/
  index.md
  guide/
    getting-started.md
  debugging/
    chrome-devtools.md
rspress.config.ts

3. rspress.config.ts

import { defineConfig } from 'rspress/config'
 
export default defineConfig({
  root: 'docs',
  title: '前端开发调试资源',
  themeConfig: {
    nav: [{ text: '调试工具', link: '/debugging/chrome-devtools' }],
    sidebar: {
      '/debugging/': [
        { text: 'Chrome DevTools', link: '/debugging/chrome-devtools' },
      ],
    },
  },
})

4. 运行

pnpm dev
pnpm build

四、 核心特性

1. Rspack 极速构建

大文档站 CI 构建时间短。

2. 默认主题

导航、侧边栏、暗色模式、TOC。

3. 全文搜索

内置搜索能力。

4. 插件生态

@rspress/plugin-llms、图片压缩、Twoslash 类型提示。

5. MDX 支持

嵌入 React 组件。

6. 多语言

i18n 路由配置。

7. 与 Modern.js 生态协同

同一 Web Infra 团队出品。

五、 适用场景

1. 黄金适用场景

• 中文技术文档与调试资源库。
• 需要比 VitePress 更快生产构建的大站。
• 工具对比、最佳实践类结构化文档。
• 国内团队，字节系工具链用户。

2. 局限适用场景

• Vue 官方生态优先 VitePress。
• Next.js 一体化（Nextra）。
• 复杂版本化文档（Docusaurus）。
• 英文国际文档主流认知度仍低于 Docusaurus。

六、 技术亮点

1. 构建性能

Rspack 带来显著构建加速。

2. 中文体验

文档、社区、案例丰富。

3. 插件 LLM 友好

plugin-llms 等面向 AI 文档消费。

4. 双框架 Demo

React/Vue 组件均可嵌入。

七、 核心概念与架构

digraph Rspress_Arch {
  rankdir=LR
  node [shape=box, style="rounded,filled", fillcolor="#f0f9ff"]
  MD [label="Markdown/MDX", fillcolor="#bae6fd"]
  Rspress [label="Rspress"]
  Rspack [label="Rspack"]
  Theme [label="Default Theme"]
  Static [label="Static Output"]
 
  MD -> Rspress
  Rspress -> Rspack
  Rspress -> Theme
  Theme -> Static
}

八、 技术局限与边界

1. 相对较新：生态与第三方主题少于 Docusaurus。
2. 国际社区：英文资料相对少。
3. 非组件沙箱：不替代 Storybook。
4. 与 VitePress 功能重叠：选型需团队统一。
5. 插件质量参差：需评估成熟度。

九、 生态地图

十、 生态集成

十一、 开发与工程化

1. 大纲同步

资源大纲.md 生成 sidebar 配置脚本化。

2. CI

- run: pnpm rspress build
- upload: dist/

3. llms.txt

配合 plugin-llms 输出 AI 可读站点地图。

十二、 性能与安全

• 静态输出，CDN 缓存友好。
• 内部调试文档部署加访问控制。
• 构建产物勿含 .env secrets。

十三、 技术对比

十四、 最佳实践

1. 侧边栏与资源大纲结构一致。
2. 大站启用 Rspack 构建缓存加速 CI。
3. 代码示例统一 pnpm 与项目规范。
4. 工具文档标注调研日期与版本。
5. 评估 plugin-llms 服务 AI 辅助阅读。

十五、 学习与社区资源

• 官方文档：https://rspress.dev/guide/start/getting-started
• GitHub：https://github.com/web-infra-dev/rspress
• Rspack：https://www.rspack.dev/