大家好，我是Echa。

好消息，2023年10月份字节跳动 ByteDance Web Infra 团队对外宣布 Rspress 1.0 正式发布。此消息一出，在Web 开发者各大论坛讨论的沸沸扬扬，有些人说又重复造轮子，有些人说为了完成KPI，粉丝们你们怎么看呢？欢迎在评论下说出自己的看法。

借此机会，小编先给大家详细介绍一下Rspress 到底是什么，能做什么，有哪些优点等等，只有彻底了解了Rspress ，才能说出自己观点。下面小编给大家一一介绍上面的问题。

全文大纲

1. Rspress 介绍
2. Rspress 项目背景
3. Rspress 构建性能到底怎么样？
4. Rspress MDX 支持
5. Rspress 有哪些文档站基础能力？
6. Rspress 扩展机制如何？
7. Rspress 有哪些功能特性？
8. Rspress 与其它 SSG 框架的区别
9. 如何部署搭建自己的 Rspress

Rspress 介绍

传送门：https://rspress.dev/

Github：https://github.com/web-infra-dev/rspress

Rspress 官网

Rspack 是由 ByteDance Web Infra 团队孵化的基于 Rust 语言开发的 Web 构建工具，拥有高性能、兼容 Webpack 生态、定制性强等多种优点，解决了我们在业务场景中遇到的非常多的问题，让很多开发者的体验有了质的提升。

Rspress 是一个基于 Rspack 的静态站点生成器，基于 React 框架进行渲染，内置了一套默认的文档主题，你可以通过 Rspress 来快速搭建一个文档站点，同时也可以自定义主题，来满足你的个性化静态站需求，比如博客站、产品主页等。当然，你也可以接入官方提供的相应插件来方便地搭建组件库文档。

为什么要做 Rspack ？

字节跳动内部存在非常多的大型前端应用，它们有着非常复杂的构建配置，十几分钟甚至半小时的构建耗时，我们尝试了多种方法去优化这些项目的编译速度，但是社区内存在的方案都或多或少存在一些问题，在对这些问题总结后，我们理解到工程师对构建工具的诉求是：

• 良好的 Dev 启动性能，npm run dev 是开发者每天需要运行很多次的命令，大型项目每次都需要等待 10 分钟，这对于工程师来说是非常痛苦的，所以优化 dev start 的时间是非常重要的；
• 良好的 Build 性能，npm run build 是在 CI/CD 环境中经常运行的指令，他决定了应用生产交付的效率，在生产环境中有些应用经常需要 20 ～ 30 分钟的构建时间，如果能缩短这里的耗时对开发链路也会非常有帮助；
• 足够灵活的配置，用户工程的配置灵活多变，并没有做到完全的统一，在之前尝试将 Webpack 配置迁移到其他构建工具的过程中我们就遇到了非常多的问题，他们的配置都很难达到 Webpack 的灵活程度；

• 生产环境的产物优化能力，在启动 Rspack 之前，我们实践了社区内的各种方案，但是他们都面临了生产环境一定程度负优化的情况，例如拆包拆的不够精细等等。所以生产环境产物优化是我们不可舍弃的功能点。

在明确这四点之后，字节跳动 ByteDance Web Infra 团队调研了社区内的所有技术方案，发现并没有完全满足我们需求的，所以ByteDance Web Infra 团队决定自研 Rspack。

Rspress 项目背景

Rspress 主要以如下的几个方向来进行建设：

• 构建性能。保证足够快的启动速度，带来良好的开发体验。
• MDX 支持。通过 MDX，我们可以方便地复用文档片段，以及在文档中渲染自定义的 React 组件。
• 文档站基础能力。包括国际化、多版本支持、全文搜索、组件库文档等。
• 可扩展性。内置插件系统，支持通过插件 API 来扩展框架功能。

这些也代表了 SSG 站点开发的一些核心需求。接下来将会根据这几个方面分别进行介绍。

Rspress 构建性能到底怎么样？

当项目越来越庞大，团队成员时常苦恼于冗长的项目启动时间，开发体验因此受到了一些负面影响，并且项目开发的时间越长，这种体验的劣化就越为明显。

我们不禁开始思考，是否能跳出目前社区工具链的限制，突破现有 SSG 框架的性能瓶颈，实现绝大多数场景的项目秒启效果？

接着，我们在这个方向上持续地探索，最终在 Rspress 上实现了这样的效果。以 Rspress 官网文档的内容为例，Rspress、Docusaurus 和 Nextra 三者的性能对比情况如下：

冷启动对比

热更新对比

冷构建对比

如果只说一种最核心的优化手段，那无疑是 Rust 前端工具链。 官方主要在两个性能敏感部分使用了 Rust 工具链：

• 前端 Bundler。传统的 Bundler 包括 webpack、Rollup 等等，对于一个前端工程而言，bundler 是各个编译工具链的集成枢纽，是一个非常关键的工程能力，对项目构建性能影响巨大。而 Rspress 使用了团队内部自研的 Rspack，Rspack 是一个基于 Rust 的 Bundler，内置多种性能优化手段，比如多线程并行编译、增量编译等等，相比社区传统的打包工具，有 5 ～ 10 倍的性能提升。
• Markdown 编译器。对于 SSG 框架中另一大编译性能瓶颈，即Markdown 编译，我们也将这一流程 Rust 化以进一步提速，定制出 Rspress 的 Markdown 编译器（即@rspress/mdx-rs）。这款编译器相比社区的 JS 版本的编译器，有近 20 倍的性能提升：

与此同时，Rspress 内部也应用了其它的诸多构建优化手段，比如主题包预打包、样式预生成 等等。这些额外的优化手段，配合强有力的 Rust 工具链，将 SSG 框架的编译性能推向了一个崭新的高度。

Rspress MDX 支持

为了保证内容开发的灵活性，Rspress 选择支持 MDX 这种内容格式。

因为 MDX 的背后实际代表了一种组件化的内容组织方式，一方面文档即组件，那么我们可以在不同文档间复用文档片段，另一方面在文档中可以引入任何自定义 React 组件，大大释放了文档开发的想象力。

Rspress 有哪些文档站基础能力？

当然，Rspress 在文档站基础能力的打磨上也做了相当多的工作，支持了如下的功能特性：

• 自动生成布局，包括导航栏、左侧侧边栏等等；
• 静态站点生成，项目构建后直出 HTML；
• 国际化，支持多语言文档；
• 全文搜索，提供开箱即用的搜索功能；
• 多版本文档管理；
• 自定义文档主题；
• 自动生成组件 Demo 预览及 Playground；

Rspress 扩展机制如何？

Rspress 内部设计了多种扩展机制，保证足够强的定制能力，包括：

• 支持自定义全局组件、全局样式、页面布局结构
• 支持构建能力扩展，包括 Rspack 配置、增加 MDX 编译插件等等
• 支持自定义主题
• 内置插件机制，支持自定义插件。

Rspress 有哪些功能特性？

接下来我们来介绍 Rspress 的主要功能特性。

自动生成布局

对于一个文档站的搭建而言，除了显示正文内容之外，我们一般还需要以下的几个布局模块：

• 导航栏，用于提供全局性的导航入口；
• 侧边栏，用于展示当前导航下的文章目录；
• 文章大纲栏，用于展示当前页面的大纲结构。

对于文档大纲，Rspress 会自动提取文档中的各级标题，生成大纲信息，并默认展示在文章页右侧，你无需其它操作。

而对于导航栏和侧边栏，官方提供了两种配置方式，你可以选择其中一种进行配置：

• 声明式配置。通过在目录中声明 _meta.json 来配置对应的数据，比如：

["introduction", "install", "start"]

• 编程式配置。通过在 Rspress 配置中指定 nav 和 sidebar 配置项来实现。

官方推荐在一般情况下使用声明式配置，这样有诸多的好处：

1. 配置文件更加简洁和清晰。
2. 文件目录结构和侧边栏目录结构的对应关系更加直观。
3. 增加或者删减侧边栏目录时，直接在当前目录中操作，而不用前往 rspress.config.ts 配置文件中定位到相应的位置然后添加/删减配置，从而减少了开发上下文切换的成本。

而编程式配置则在某些需要动态生成配置的场景中非常有用，比如 Rspress 官方的 TypeDoc 插件 会根据 TypeDoc 提供的一份 json 数据自动转换为 nav 和 sidebar 的配置。

MDX 支持

MDX 是一种功能强大的内容开发方式。你不仅仅可以像往常一样编写 Markdown 文件，而且可以在 Markdown 的内容中使用 React 组件：

除此之外，Rspress 还支持了一些特定的语法，如：

• 自定义容器语法。
• FrontMatter 元数据定义。
• 代码行高亮语法。

SSG

Rspress 是一个标准的 SSG 框架，在生产环境的构建中，它会自动帮你生成静态站点，即生成各个页面的 HTML 内容，在构建完成之后，HTML 会出现在默认的产物目录中。

随后，你可以将这个产物目录的内容部署到任何静态站点托管服务上，比如 Github Pages、Netlify、Vercel 等等。

同时，官方也提供了配置让你能够很方便地自定义 SSG 生成的 HTML 内容。

国际化（i18n）

国际化在一个文档类型的站点中是一个很常见的需求，而 Rspress 将国际化的能力封装得足够简单易用，在框架中我们将国际化抽象为如下的需求：

• 如何定义 I18n 数据源？
• 如何进行不同语言下的站点配置？
• 如何组织不同语言版本的文档目录？
• 如何自定义组件中使用 I18n 数据源？

框架已经为你支持了这些需求场景，你可以根据 I18n 教程 来一步步为你的站点实现国际化。

多版本文档

在某些场景中，我们需要进行多版本文档管理，而 Rspress 已经内置了多版本文档的支持，一方面你可以通过简单的配置来开启这个能力，另一方面你只需要按照往常的写法来组织目录即可，不引入非必要的目录和概念，将心智负担降到最低：

// 配置文件
import { defineConfig } from 'rspress/config';

export default defineConfig({
  multiVersion: {
    default: 'v1',
    versions: ['v1', 'v2'],
  },
});

// 目录结构
docs
├── v1
│   ├── README.md
│   └── guide
│       └── README.md
└── v2
    ├── README.md
    └── guide
        └── README.md

全文搜索

Rspress 中提供开箱即用的全文搜索能力，你无需任何配置即可接入，底层基于开源的 FlexSearch 引擎实现，效果如下：

全文搜索

自定义主题

Rspress 支持两种自定义主题的方式：

1. 基于默认主题扩展。在默认主题的各个组件中，提供了许多插槽让你能添加自定义的布局内容，比如接入 documate 提供的 AI 问答组件：

// theme/index.tsx
import Theme from 'rspress/theme';
import { NoSSR } from 'rspress/runtime';
import { Documate } from '@documate/react';
import '@documate/react/dist/style.css';

const Layout = () => (
  
        
      
    }
  />
);

export default {
  ...Theme,
  Layout,
};

export * from 'rspress/theme';

效果如下：

2. 完全自定义主题。如果你想从头开发一套自定义主题，可以重新自定义 Layout 的内容，并借助 Rspress 提供的各个 Runtime API （如 usePageData）来获取编译时数据、路由等信息。

插件机制

插件机制是 Rspress 至关重要的部分，它可以让你在搭建站点的过程中，方便地扩展框架的功能。

组件文档

Rspress 提供了 preview 插件，可以自动为你生成组件预览。当你注册 preview 插件后，在 mdx 文件中声明如下的代码块：

import React from 'react';
import { Tag, Space } from '@arco-design/web-react';
import '@arco-design/web-react/dist/css/arco.css';
const COLORS = [
  'red',
  'orangered',
  'orange',
  'gold',
  'lime',
  'green',
  'cyan',
  'blue',
  'arcoblue',
  'purple',
  'pinkpurple',
  'magenta',
  'gray',
];

export default () => {
  return (
    
      {COLORS.map((color, i) => (
        
          {color}
        
      ))}
    
  );
};

那么你可以看到如下的预览效果：

当然，插件同时也支持移动端预览模式，你可以通过插件配置开启，预览效果如下：

demo 实时 Playground

对于组件文档，如果能提供组件的实时编辑的能力，将能大大提高文档的交互体验。

为了实现这个功能，你只需要注册官方的 playground 插件，然后在 .mdx 文件中声明你的代码块。（这里以上面的代码块为例）

接着，你将会在文档中看到下面的 playground 效果：

内置流畅的转场动画

View Transition API 是现代浏览器原生提供的一组 API，用于实现页面跳转过程中的过渡效果。在 Rspress 中我们也跟进了这个特性，基于 View Transition 实现了文档的过渡动画，而未使用任何第三方 SPA 的动画方案。在未来，我们也会探索出更多的动画效果，进一步提升体验。

export default defineConfig({
  themeConfig: {
    // 开启 View Transition 过渡
    enableContentAnimation: true,
  },
});

Rspress 与其它 SSG 框架的区别

与 Docusaurus 的区别

Docusaurus 是 Meta 开源的一款 SSG 框架，它和 Rspress 一样使用 React 作为渲染框架，且支持 MDX，但 Rspress 与 Docusaurus 的区别主要在于：

1. Rspress 的构建性能更好。Rspress 基于 Rust 前端工具链，项目启动/构建速度快于 Docusaurus 5 ~ 10 倍，详情可以参考构建性能。
2. Rspress 的配置更简单，上手成本更低。Rspress 的配置更加简单，不引入过多的概念，尽可能降低心智负担，比如提供开箱即用的搜索功能、符合直觉的多版本文档管理方式等等。
3. Rspress 架构上对 Bundler 提供了更上层的抽象。对于 webpack、Rspack 这类底层的 Bundler，其配置项繁琐且不易上手。Docusaurus 选择直接暴露底层 Bundler 的配置项，而 Rspress 则对 Bundler 进行了更上层的抽象，提供了更加简单易用的配置项，比如你可以通过 builderConfig.html.tags 轻松添加 中的标签，而不用通过 Bundler 来注册 html-webpack-plugin 相关插件。

与 Nextra 的区别

Nextra 是 Vercel 开源的一款 SSG 框架，它也和 Rspress 一样使用 React 作为渲染框架，且支持 MDX。Rspress 与 Nextra 的区别主要在于：

1. Rspress 的构建性能更好。这一点可参考「与 Docusaurus 的区别」。
2. Rspress 整体更加轻量。Nextra 需要依赖 Next.js，其 SSG 流程也是基于 Next.js 的，因此 SSG 产物中并非纯粹的 HTML 文件，而是额外包含了一些 Next.js 的运行时代码，一方面导致了 Nextra 的产物体积更大，另一方面需要在部署时以应用的方式部署(使用 next start 命令)，而不能以纯静态站点的方式部署。但 Rspress 没有和任何应用框架绑定，因此产物更加轻量，可以很方便地以纯静态站点的方式部署。

与 VitePress 的区别

VitePress 是一款基于 Vite 静态站点生成器，它的特点是使用 Vue 作为渲染框架，且性能非常优秀。Rspress 与 VitePress 的区别主要在于：

1. Rspress 使用 React 作为渲染框架，而 VitePress 使用 Vue 作为渲染框架。
2. Rspress 使用 MDX 作为内容开发方式，而 VitePress 使用 Markdown 作为内容开发方式，并在 Markdown 中支持 Vue 组件，这同时也导致了底层编译工具链实现上的差异。
3. 构建性能上，在开发阶段，Rspress 和 VitePress 都能很快地启动一个项目，而在生产环境下，VitePress 需要基于 Rollup 打包项目，因此会面临其他基于 JavaScript 的工具链类似的性能问题，此时 Rspress 会有更快的构建速度。

如何部署搭建自己的 Rspress

1. 初始化项目

方式一：通过脚手架创建

你可以通过 Rspress 脚手架命令来创建项目:

npm create rspress@latest
或者：yarn create rspress@latest
或者：pnpm create rspress@latest
或者：bun create rspress@latest

然后按照提示输入项目名称，即可创建一个 Rspress 项目。

方式二：手动创建

首先，你可以通过以下命令创建一个新目录：

mkdir rspress-app && cd rspress-app

执行 npm init -y 来初始化一个项目。你可以使用 npm、yarn 或 pnpm 安装 Rspress:

npm install rspress typescript ts-node -D
或者： yarn add rspress typescript ts-node -D
或者：pnpm install rspress typescript ts-node -D
或者：bun add rspress typescript ts-node -D

然后通过如下命令创建文件:

mkdir docs && echo '# Hello World' > docs/index.md

在 package.json 中加上如下的脚本:

{
  "scripts": {
    "dev": "rspress dev",
    "build": "rspress build",
    "preview": "rspress preview"
  }
}

然后初始化一个配置文件 rspress.config.ts:

import { defineConfig } from 'rspress/config';

export default defineConfig({
  // 文档根目录
  root: 'docs',
});

同时新建 tsconfig.json，内容如下:

{
  "compilerOptions": {
    "esModuleInterop": true,
    "jsx": "react-jsx"
  }
}

启动 Dev Server

通过如下命令启动本地开发服务:

npm run dev

这样 Rspress 将启动开发服务。

生产环境构建

通过如下命令构建生产环境的产物:

npm run build

默认情况下，Rspress 将会把产物打包到 doc_build 目录。

本地预览产物

通过如下命令启动本地预览服务:

npm run preview

这样 Rspress 将启动产物预览服务。

最后

一台电脑,一个键盘,尽情挥洒智慧的人生;

几行数字,几个字母,认真编写生活的美好;

一 个灵感,一段程序,推动科技进步,促进社会发展。

创作不易，喜欢的老铁们加个关注，点个赞，打个赏，后面会不定期更新干货和技术相关的资讯，速速收藏，谢谢！你们的一个小小举动就是对小编的认可，更是创作的动力。

创作文章的初心是：沉淀、分享和利他。既想写给现在的你，也想贪心写给 10 年、20 年后的工程师们，现在的你站在浪潮之巅，面对魔幻的互联网世界，很容易把一条河流看成整片大海。未来的读者已经知道了这段技术的发展历史，但难免会忽略一些细节。如果未来的工程师们真的创造出了时间旅行机器，可以让你回到现在。那么小编的创作就是你和当年工程师们的接头暗号，你能感知到他们在这个时代的键盘上留下的余温。