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

# 快速开始

本文档将介绍如何接入 Rsdoctor 能力。

## 环境要求

- Node.js `^20.19.0 || >=22.12.0`
- Rspack 2.0 及以上版本。Rsdoctor 2.0 不再支持 Rspack 1.x。

## 第一步：安装依赖

### Rspack 项目

基于 Rspack 的项目（比如 Rsbuild 或 Rslib），安装以下依赖：


```sh [npm]
npm add @rsdoctor/core -D
```

```sh [yarn]
yarn add @rsdoctor/core -D
```

```sh [pnpm]
pnpm add @rsdoctor/core -D
```

```sh [bun]
bun add @rsdoctor/core -D
```

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

***

## 第二步：注册插件

依赖安装完成后，你需要在项目中接入 Rsdoctor 插件，下面是一些常见工具和框架的示例：

### Rspack 项目

在 `rspack.config.mjs` 的 [plugins](https://www.rspack.rs/config/plugins.html#plugins) 中初始化 `RsdoctorRspackPlugin`，参考：

```js title="rspack.config.mjs"
import { RsdoctorRspackPlugin } from '@rsdoctor/core';

export default {
  // ...
  plugins: [
    // 仅在 RSDOCTOR 为 true 时注册插件，因为插件会增加构建耗时
    process.env.RSDOCTOR &&
      new RsdoctorRspackPlugin({
        // 插件选项
      }),
  ].filter(Boolean),
};
```

- **Options:** 插件提供了一些配置项，请参考 [Options](/zh/config/options/options.md)。

### Rsbuild 项目

Rsbuild 内置了对 Rsdoctor 的支持，不需要手动注册插件。详见 [Rsbuild - 使用 Rsdoctor](https://rsbuild.rs/zh/guide/debug/rsdoctor)。

### Modern.js 项目

在 `modern.config.ts` 的 [tools.bundlerChain](https://modernjs.dev/configure/app/tools/rspack) 中初始化插件，参考：

```ts title="modern.config.ts"
import { RsdoctorRspackPlugin } from '@rsdoctor/core';

export default {
  // ...
  tools: {
    rspack(config, { appendPlugins }) {
      // 仅在 RSDOCTOR 为 true 时注册插件，因为插件会增加构建耗时
      if (process.env.RSDOCTOR) {
        appendPlugins(
          new RsdoctorRspackPlugin({
            // 插件选项
          }),
        );
      }
    },
  },
};
```

- **Options:** 插件提供了一些配置项，请参考 [Options](/zh/config/options/options.md)。

### Next.js 项目

#### 第一步：注册 Rsdoctor 插件

在 `next.config.ts` 的 [Rspack 配置](https://rspack.rs/guide/tech/next) 中初始化 [RsdoctorRspackPlugin](#rspack-%E9%A1%B9%E7%9B%AE) 插件。

```ts title="next.config.ts"
import type { NextConfig } from 'next';
import { RsdoctorRspackPlugin } from '@rsdoctor/core';

const nextConfig: NextConfig = {
  /* config options here */
  webpack: (config) => {
    if (config.name === 'client') {
      config.plugins.push(
        new RsdoctorRspackPlugin({
          disableClientServer: true,
        }),
      );
    } else if (config.name === 'server') {
      config.plugins.push(
        new RsdoctorRspackPlugin({
          disableClientServer: true,
          output: {
            reportDir: './.next/server',
          },
        }),
      );
    }
    return config;
  },
};

export default nextConfig;
```

- **Options:** 插件提供了一些配置项，请参考 [Options](/zh/config/options/options.md)。

#### 第二步：执行构建

执行 **build** 命令，Rsdoctor 会在本地仓库产物中生成对应的报告数据。


```sh [npm]
npm run build
```

```sh [yarn]
yarn run build
```

```sh [pnpm]
pnpm run build
```

```sh [bun]
bun run build
```

```sh [deno]
deno run npm:build
```

#### 第三步：打开报告

安装 [@rsdoctor/cli](/zh/guide/start/cli.md) 后，**package.json** 里添加如下 scripts 命令，执行 **client:rsd** 或者 **server:rsd** 可打开对应构建器的报告：


```sh [npm]
npm add @rsdoctor/cli -D
```

```sh [yarn]
yarn add @rsdoctor/cli -D
```

```sh [pnpm]
pnpm add @rsdoctor/cli -D
```

```sh [bun]
bun add @rsdoctor/cli -D
```

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

```ts
  "scripts": {
    "client:rsd": "rsdoctor analyze --profile .next/.rsdoctor/manifest.json", // Rsdoctor's client report path
    "server:rsd": "rsdoctor analyze --profile .next/server/.rsdoctor/manifest.json" // Rsdoctor's server report path
  }
```

#### 📢 Next.js 项目使用注意

Next.js 在 `build` 执行结束后会终止终端服务，导致 Rsdoctor 在构建过程中运行的报告页面服务器关闭。为解决此问题，你可以使用 [@rsdoctor/cli](/zh/guide/start/cli.md) 重新打开报告页面，无需重新执行构建操作。具体方法见[第三步](#%E7%AC%AC%E4%B8%89%E6%AD%A5%E6%89%93%E5%BC%80%E6%8A%A5%E5%91%8A)或本地执行 rsdoctor 命令：

例如 Rsdoctor 的构建产物在 `.next/server/chunks/.rsdoctor/manifest.json` 路径，则可通过执行下面命令来打开报告页面：

```bash
rsdoctor analyze --profile .next/server/chunks/.rsdoctor/manifest.json

```

### Vue 项目

从 `@rsdoctor/core` 导入 `RsdoctorRspackPlugin` 并在配置文件中初始化。以下是 Rsbuild 项目的示例：

```ts title="rsbuild.config.ts"
import { defineConfig } from '@rsbuild/core';
import { pluginVue } from '@rsbuild/plugin-vue';
import { RsdoctorRspackPlugin } from '@rsdoctor/core';

export default defineConfig({
  plugins: [pluginVue()],
  performance: {
    buildCache: false,
  },
  tools: {
    bundlerChain: (chain, { CHAIN_ID }) => {
      chain.plugin('Rsdoctor').use(RsdoctorRspackPlugin, [
        {
          // 插件选项
        },
      ]);
    },
  },
});
```

- **Options:** 插件提供了一些配置项，请参考 [Options](/zh/config/options/options.md)。

***

## 第三步：执行构建

现在你可以在项目内执行 **build** 命令，在完成构建后，Rsdoctor 会自动打开本次构建的分析页面。

```bash
# 开启 Rsdoctor
RSDOCTOR=true npm run build

# 未开启 Rsdoctor
npm run build
```

:::tip
Rsdoctor 插件提供了一些配置项，请参考 [Options](/zh/config/options/options.md)。
:::