> 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 2.0 发布横幅](https://assets.rspack.rs/rsdoctor/rsdoctor-banner-2-0.png)
_2026 年 10 月_

# Rsdoctor 2.0 发布公告


![yifancong](https://github.com/yifancong.png)

yifancong

[](https://github.com/yifancong)

@yifancong

![Jiahan Chen](https://github.com/chenjiahan.png)

Jiahan Chen

[](https://github.com/chenjiahan)

@chenjiahan

我们很高兴地宣布 Rsdoctor 2.0 正式发布！🎉

Rsdoctor 是专为 Rspack 打造的构建分析工具，既能通过可视化报告帮助开发者排查问题，也能为 agent 提供数据，实现自动化诊断与优化。

本次更新的主要亮点包括：

- [面向 agent 的构建分析](#build-analysis-for-agents)：同一份分析数据，既支持开发者可视化排查，也支持 agent 自动化分析
- [更小的安装体积](#a-smaller-package-and-dependency-graph)：安装体积减少 56%，依赖数量减少 78%
- [更快的分析速度](#faster-analysis)：构建分析耗时减少 57%
- [更快的增量构建](#faster-rebuilds-in-watch-mode)：减少重构建过程中的分析开销，HMR 耗时降低约 **47%**
- [改进多 compiler 支持](#one-report-for-every-compiler)：在同一份报告中查看多个 compiler 的分析结果

## 面向 agent 的构建分析 \{#build-analysis-for-agents}

随着 agent 承担越来越多的分析、诊断和优化工作，我们希望 Rsdoctor 能为这些任务提供所需的构建数据，帮助 agent 理解项目的构建过程并找到优化方向。

Rsdoctor 的可视化界面主要服务于开发者。为了让 agent 也能使用这些数据，我们在 Rsdoctor 1.x 中推出了 [Agent CLI](/zh/guide/start/ai.md#agent-cli)。它直接读取 `rsdoctor-data.json`，支持检索和过滤报告数据，并返回结构化 JSON，让 agent 可以按需查询、逐步排查问题。

在 2.0 中，Agent CLI 成为推荐的自动化分析方式。配合 [Rsdoctor analysis skill](/zh/guide/start/ai.md#agent-skills)，agent 可以根据任务选择查询命令并分析结果。首先，在项目中安装 Agent CLI，也可以为 agent 安装配套的 skill：

```bash
# 安装 Agent CLI
pnpm add -D @rsdoctor/agent-cli

# 安装 Rsdoctor analysis skill（可选）
npx skills add rstackjs/agent-skills --skill rsdoctor-analysis
```

接下来，在 Rsdoctor 插件中配置 [brief 模式](/zh/config/options/output.md#mode-brief)，生成供 agent 查询的 `rsdoctor-data.json`：

```js
new RsdoctorRspackPlugin({
  output: {
    mode: 'brief',
    options: { type: ['json'] },
  },
});
```

配置后运行 `pnpm run build`。临时生成 JSON 数据时，也可以使用 `RSDOCTOR_OUTPUT=json pnpm run build`。

生成报告后，就可以用自然语言向 agent 提出分析需求，例如：

```text
使用 Rsdoctor 分析当前项目，找出可以优化产物体积的方向。
```

agent 会根据问题调用相应的 `rsdoctor-agent` 命令，结合项目上下文定位大 chunk、重复依赖等问题，并继续查询模块引用链、loader 耗时或 tree shaking 失败原因，逐步缩小排查范围并提出优化建议。

![Agent CLI 演示](https://assets.rspack.rs/others/assets/rsdoctor/agent-cli-2.gif)
随着 agent 的分析入口统一到 Agent CLI，我们在 Rsdoctor 2.0 中下线了原有的 MCP Server 用法。使用 `@rsdoctor/mcp-server` 的项目可以参考 [2.0 迁移指南](/zh/guide/migration/migration-v2.md#ai-工作流迁移)完成迁移。

## 更小的安装体积 \{#a-smaller-package-and-dependency-graph}

Rsdoctor 2.0 将原先分散在多个包中的分析能力整合到 `@rsdoctor/core`，并精简运行时依赖。这减少了安装时需要下载的包数量，也降低了本地开发和 CI 环境中的磁盘占用。

经过这些调整，Rsdoctor 2.0 的安装体积从 25.5 MB 降至 11.1 MB，依赖数量从 83 个减少到 18 个：

| 指标   | Rsdoctor 1.x | Rsdoctor 2.0 |        降幅 |
| ---- | -----------: | -----------: | --------: |
| 安装体积 |      25.5 MB |      11.1 MB | **56.6%** |
| 依赖数量 |           83 |           18 | **78.3%** |

## 更快的分析速度 \{#faster-analysis}

自 1.5 起，Rsdoctor 已默认使用 Rspack 原生插件采集构建数据。2.0 进一步精简了 JavaScript 侧的实现，将更多数据采集逻辑交给原生插件，原有的 [`experiments.enableNativePlugin`](/zh/config/options/experiments.md#enablenativeplugin) 配置也随之移除。

这些优化进一步降低了 Rsdoctor 的分析开销。在基准测试中，Rsdoctor 2.0 相比 1.4 的耗时减少了 57%：

| 指标     | Rsdoctor 1.4 | Rsdoctor 2.0 |        降幅 |
| ------ | -----------: | -----------: | --------: |
| 分析耗时   |      18.07 s |       7.77 s | **57.0%** |
| 峰值 RSS |    2,186 MiB |    1,755 MiB | **19.7%** |

## 更快的增量构建 \{#faster-rebuilds-in-watch-mode}

在开发过程中开启 Rsdoctor，可以随着代码修改持续分析构建结果，但分析带来的额外开销也会增加每次等待更新的时间。Rsdoctor 2.0 优化了 watch 模式下的分析流程，让你在保留构建分析能力的同时，更快地看到修改效果。

现在每次重构建时，Rsdoctor 会复用已有的分析结果和报告服务。对于开发时不必每次计算的模块和产物 gzip 体积，watch 模式会跳过计算，并采用更快的压缩级别保存报告，减少等待时间。

在基准测试中，这些优化带来了以下收益：

| 基准测试指标     |      优化前 |     优化后 |      耗时降幅 |
| ---------- | -------: | ------: | --------: |
| HMR 耗时中位数  |   6.81 s |  3.64 s |   **47%** |
| 重复构建中的分析耗时 | 250.9 ms | 14.2 ms | **94.3%** |

## 改进多 Compiler 支持 \{#one-report-for-every-compiler}

Rsdoctor 2.0 改进了对多 compiler 的支持，以改善在全栈框架中的使用体验。

Rsdoctor 会自动将多个 compiler 的分析结果聚合到一份报告中。你可以通过 compiler 名称切换查看各自的结果，无需在多份报告之间来回查找。插件创建的 [child compiler](https://github.com/web-infra-dev/rsdoctor/pull/1842) 也会被自动识别，并与 main compiler 的数据分开展示。

![包含 main compiler 和带 Child 标签的 child-assets 的 compiler 选择器](https://assets.rspack.rs/rsdoctor/child_compiler.png)
这些能力默认开启。如果需要自定义报告分组，例如将 SSR 项目的客户端和服务端构建归为一组，可以为插件实例指定相同的分组名称：

```ts
new RsdoctorRspackPlugin({
  multiCompiler: { group: 'ssr' },
});
```

同一进程中的 compiler 若属于互不相关的构建，也可以通过 [`multiCompiler: false`](/zh/config/options/multiCompiler.md) 关闭自动聚合。Agent CLI 同样支持[选择 compiler](/zh/guide/start/ai.md#selecting-a-compiler)，让 agent 针对指定构建进行分析。

## 产物分析界面改进 \{#refined-bundle-analysis}

分析产物体积时，我们往往需要先找到较大的产物或 chunk，再逐层查看其中的模块。随着项目规模增长，模块可能分布在多层目录中，浏览和定位也会变得费时。Rsdoctor 2.0 围绕这一过程，改善了 Bundle Size 页面的浏览体验。

在 Tree Graph 中，即使产物包含数千个模块，展开目录和连续滚动也能更加流畅。通过虚拟滚动和渲染缓存，页面只渲染视窗附近的节点，并减少提示框等交互组件在滚动时的开销，让你更顺畅地查找模块、查看详情：

**优化前**

![Tree Graph 优化前](https://assets.rspack.rs/rsdoctor/tree-graph-before.gif)

**优化后**

![Tree Graph 优化后](https://assets.rspack.rs/rsdoctor/tree-graph-after.gif)

Treemap 则让你更方便地从整体体积分布深入查看具体模块：点击即可缩放到关注的区域，再通过面包屑导航返回上层。需要查看大型产物时，可以进入全屏模式或收起侧边栏，为图表留出更多空间；布局也会随窗口大小调整。

你还可以筛选 JavaScript 产物，将注意力集中在相关代码上，并通过统一的 Stat、Parsed 和 Gzipped 体积指标，从不同角度了解模块的体积占比。

> 相关 PR：[#1705](https://github.com/web-infra-dev/rsdoctor/pull/1705)、[#1782](https://github.com/web-infra-dev/rsdoctor/pull/1782)、[#1830](https://github.com/web-infra-dev/rsdoctor/pull/1830)、[#1839](https://github.com/web-infra-dev/rsdoctor/pull/1839)。

## 如何升级 \{#how-to-upgrade}

升级到 Rsdoctor 2.0 时，主要需要关注以下变化：

- [运行环境](/zh/guide/migration/migration-v2.md#检查构建工具)：要求 Node.js `^20.19.0 || >=22.12.0` 和 Rspack 2.0 及以上版本。
- [包名与模块格式](/zh/guide/migration/migration-v2.md#更新-rspack-插件)：使用 `@rsdoctor/core` 替换 `@rsdoctor/rspack-plugin`，并使用 ESM 导入。
- [AI 工作流](/zh/guide/migration/migration-v2.md#ai-工作流迁移)：从已移除的 `@rsdoctor/mcp-server` 迁移到 Agent CLI。
- Rsdoctor 2.0 不再兼容 webpack，使用 webpack 的项目可以继续使用 Rsdoctor 1.x。

完整的升级步骤、配置变更和验证方法，请参考 [Rsdoctor 2.0 升级指南](/zh/guide/migration/migration-v2.md)。指南也提供了迁移 skill，可让 agent 协助完成升级。

欢迎试用 Rsdoctor 2.0 并分享反馈，完整更新内容见 [release 页面](https://github.com/web-infra-dev/rsdoctor/releases)。

## 致谢 \{#acknowledgements}

感谢所有参与贡献和提供反馈的开发者与用户。你们的参与帮助我们完善了 Rsdoctor 2.0 ❤️

[![Contributors](https://contrib.rocks/image?repo=web-infra-dev/rsdoctor&columns=16)](https://github.com/web-infra-dev/rsdoctor/graphs/contributors)