> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt.

# 快速上手

通过本章节来了解如何快速上手并使用 Rspack。

- [创建新项目](#创建新项目)：使用 CLI 创建一个全新的 Rspack 或 Rsbuild 项目。
- [从现有项目迁移](#从现有项目迁移)：从一个基于 webpack 的项目迁移到 Rspack。

## 生态

作为一个底层打包工具，Rspack 拥有丰富的技术生态，包含多种框架、工具和解决方案。这些生态项目涵盖了从框架到开发工具的各个方面，能够满足不同场景下的开发需求，提供开箱即用的体验。

查看 [生态](/zh/guide/start/ecosystem.md) 页面来探索这些生态项目。

## 环境准备

Rspack 支持使用 [Node.js](https://nodejs.org/)、[Deno](https://deno.com/) 或 [Bun](https://bun.sh/) 作为 JavaScript 运行时。

你可以参考以下安装指南，选择其中一种运行时：

- [安装 Node.js](https://nodejs.org/zh-cn/download)
- [安装 Bun](https://bun.com/docs/installation)
- [安装 Deno](https://docs.deno.com/runtime/getting_started/installation/)

:::tip 版本要求

- Rspack v2 要求 Node.js 版本 20.19+, 22.12+。
- Rspack v1 要求 Node.js 18.12.0 或更高版本。

:::

:::details 针对不支持的平台

如果您正在使用小众平台，Rspack 可能没有提供原生支持。在这种情况下，请手动安装 `@rspack/binding-wasm32-wasi` 作为备用方案。Wasm 版本可以在大多数平台上运行。

当前支持的平台：

- `darwin-arm64`
- `darwin-x64`
- `linux-arm64-gnu`
- `linux-arm64-musl`
- `linux-riscv64-gnu`
- `linux-riscv64-musl`
- `linux-ppc64-gnu`
- `linux-s390x-gnu`
- `linux-x64-gnu`
- `linux-x64-musl`
- `win32-arm64-msvc`
- `win32-ia32-msvc`
- `win32-x64-msvc`

:::

## 创建新项目

### 使用 Rsbuild

Rsbuild 是由 Rspack 驱动的高性能构建工具，由 Rspack 团队开发。它默认包含了一套精心设计的构建配置，提供开箱即用的开发体验，并能够充分发挥出 Rspack 的性能优势。

我们推荐使用 [Rsbuild](https://rsbuild.rs/) 来创建新项目，执行如下命令即可：


```sh [npm]
npm create rsbuild@latest
```

```sh [yarn]
yarn create rsbuild
```

```sh [pnpm]
pnpm create rsbuild@latest
```

```sh [bun]
bun create rsbuild@latest
```

```sh [deno]
deno init --npm rsbuild@latest
```

> 更多信息参考 [Rsbuild - 快速上手](https://rsbuild.rs/zh/guide/start/quick-start)。

### 使用 Rspack CLI

Rspack CLI 是对标 webpack CLI 的工具，提供基础的 `serve` 和 `build` 构建命令。

执行如下命令即可创建基于 Rspack CLI 的项目：


```sh [npm]
npm create rspack@latest
```

```sh [yarn]
yarn create rspack
```

```sh [pnpm]
pnpm create rspack@latest
```

```sh [bun]
bun create rspack@latest
```

```sh [deno]
deno init --npm rspack@latest
```

然后按照提示操作。

### 非交互模式

[create-rspack](https://www.npmjs.com/package/create-rspack) 和 [create-rsbuild](https://www.npmjs.com/package/create-rsbuild) 支持通过命令行选项进入非交互模式。使用该模式可以跳过所有提示，直接创建项目，适合脚本、CI 以及 coding agents 等自动化场景。

例如，以下命令将在 `my-app` 目录中创建一个 React 应用：

```bash
# Rspack CLI
npx -y create-rspack --dir my-app --template react
# Rsbuild
npx -y create-rsbuild --dir my-app --template react
# 使用缩写
npx -y create-rsbuild -d my-app -t react
```

## 手动安装

首先创建一个项目目录，并生成一个 npm `package.json` 文件：

```bash
mkdir rspack-demo
cd rspack-demo
npm init -y
```

然后安装 [@rspack/core](https://www.npmjs.com/package/@rspack/core) 和 [@rspack/cli](https://www.npmjs.com/package/@rspack/cli) 为 dev 依赖：


```sh [npm]
npm add @rspack/core @rspack/cli -D
```

```sh [yarn]
yarn add @rspack/core @rspack/cli -D
```

```sh [pnpm]
pnpm add @rspack/core @rspack/cli -D
```

```sh [bun]
bun add @rspack/core @rspack/cli -D
```

```sh [deno]
deno add npm:@rspack/core npm:@rspack/cli -D
```

更新构建脚本以使用 Rspack CLI：

```js title="package.json"
{
  "scripts": {
    "dev": "rspack dev",
    "build": "rspack build",
    "preview": "rspack preview"
  }
}
```

接下来，查看 [配置 Rspack](/zh/config/index.md) 来了解如何配置 Rspack。

## 从现有项目迁移

如果你需要从一个现有项目迁移迁移到 Rspack 技术栈，可以参考以下指南：

- [从 webpack 迁移到 Rspack](/zh/guide/migration/webpack.md)
- [从 webpack 迁移到 Rsbuild](https://rsbuild.rs/zh/guide/migration/webpack)
- [从 Create React App 迁移到 Rsbuild](https://rsbuild.rs/zh/guide/migration/cra)
- [从 Vue CLI 迁移到 Rsbuild](https://rsbuild.rs/zh/guide/migration/vue-cli)
- [从 Vite 迁移到 Rsbuild](https://rsbuild.rs/zh/guide/migration/vite)
- [从 Tsup 迁移到 Rslib](https://rslib.rs/zh/guide/migration/tsup)
- [从 Storybook 迁移](/zh/guide/migration/storybook.md)

## 安装 canary 版本

当你需要测试或验证 Rspack 未发布至稳定版的功能时，可能需要使用 canary 版本。

Rspack canary 版本的 scope 会带有 `-canary` 后缀。例如 `@rspack/core` 的 canary 包名为 `@rspack-canary/core`。要使用这些版本，你可以配置包管理器（npm/yarn/pnpm/bun）的 overrides。

以下是使用 pnpm overrides 的示例：

```json title="package.json"
{
  "pnpm": {
    "overrides": {
      "@rspack/core": "npm:@rspack-canary/core@latest"
    },
    "peerDependencyRules": {
      "allowAny": ["@rspack/*"]
    }
  }
}
```

此外，Rspack 社区提供了 [install-rspack](https://github.com/rstackjs/install-rspack) 工具来方便地安装 canary 版本：

```shell
npx install-rspack --version latest # 安装当前的 latest 版本
npx install-rspack --version canary # 安装当前的 canary 版本
npx install-rspack --version 1.0.0-canary-d614005-20250101082730 # 安装指定的 canary 版本
```