---
title: 使用 Rspack
sidebar_position: 1
---

# 使用 Rspack

import Rspack from '@modern-js/builder-doc/docs/zh/shared/rspack-tip.mdx';

<Rspack />

**Modern.js 提供开箱即用的 Rspack 支持**，你可以在成熟的 Webpack 和更快的 Rspack 之间进行切换。

这篇文档会向你介绍如何在 Modern.js 中开启 Rspack 构建模式。

## 初始化 Rspack 项目

Modern.js 生成器会提供一个可交互的问答界面，只需将构建工具选择为 **Rspack**，即可创建一个 Rspack 项目:

import InitRspackApp from '@site-docs/components/init-rspack-app';

<InitRspackApp />

项目创建完成后，在项目中执行 `pnpm run dev` 即可体验项目，更多信息可参考[快速上手](/guides/get-started/quick-start.html)。

:::tip
在使用 Rspack 作为打包工具时，由于部分能力尚在开发中，以下 features 暂时无法使用，我们将在未来提供支持：

- Storybook 调试
- 客户端渲染（CSR）使用 [useLoader](/guides/basic-features/data-fetch.html)

:::

## 开启 Rspack 构建

在一个已有的 Modern.js 项目中，你可以通过执行 `pnpm run new` 来启用 Rspack 构建：

```bash
$ pnpm run new
? 请选择你想要的操作 启用可选功能
? 请选择功能名称 启用「Rspack 构建」
```

执行以上命令后，在 `modern.config.ts` 中添加 Rspack 相关配置即可：

```diff title=modern.config.ts
import appTools, { defineConfig } from '@modern-js/app-tools';

+ export default defineConfig<'rspack'>({
  plugins: [
    appTools({
+     bundler: 'experimental-rspack',
    }),
  ],
});
```

## 配置迁移

开启 Rspack 构建能力后，还需要参考 [配置差异](https://modernjs.dev/builder/guide/advanced/rspack-start.html#从-webpack-迁移到-rspack) 进行进一步的配置迁移。

## Rspack 和 Modern.js 的版本关系

通常情况下，Modern.js 内会集成 Rspack 的最新版本，通过 `npx modern upgrade` 即可将当前项目中的 Modern.js 相关依赖以及内置的 Rspack 更新至最新版本。

但 Modern.js 对于 Rspack 的依赖方式为锁版本方式(非自动升级)，由于发版周期不同步等原因，可能会出现 Modern.js 内集成的 Rspack 版本落后于 Rspack 最新版本的情况。

当你执行 dev / build 命令时，Modern.js 会自动打印当前使用的 Rspack 版本：

![rspack_version_log](https://lf3-static.bytednsdoc.com/obj/eden-cn/6221eh7uhbfvhn/modern/img_v2_dfcf051f-21db-4741-a108-d9f7a82c3abg.png)

#### 修改内置 Rspack 版本

可以使用 pnpm / yarn / npm 等包管理工具自带的依赖升级功能来将 Rspack 强制升级到指定版本。

以 pnpm 为例，可通过 `overrides` 以下依赖更新 Rspack 版本:

```json title=package.json
{
  "pnpm": {
    "overrides": {
      "@rspack/core": "nightly",
      "@rspack/dev-client": "nightly",
      "@rspack/dev-middleware": "nightly",
      "@rspack/plugin-html": "nightly",
      "@rspack/postcss-loader": "nightly"
    }
  }
}
```

:::tip Nightly 版本介绍
每天，Rspack 会自动构建基于最新代码的 nightly 版本，用于测试和及早发现错误。
通常情况下，这些版本是可用的。如果发现问题，我们会及时进行修复。但是，如果 Rspack 有一些 break change，需要 Modern.js 同步修改代码，那么我们建议等待下一个 Modern.js 版本再进行更新。
:::

如果想了解其他包管理工具锁定依赖版本的示例，可以参考：[锁定子依赖](/guides/get-started/upgrade.html#%E9%94%81%E5%AE%9A%E5%AD%90%E4%BE%9D%E8%B5%96)。
