2026 年 10 月

#Rsdoctor 2.0 发布公告

yifancong

@yifancong

Jiahan Chen

@chenjiahan

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

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

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

• 面向 agent 的构建分析：同一份分析数据，既支持开发者可视化排查，也支持 agent 自动化分析
• 更小的安装体积：安装体积减少 56%，依赖数量减少 78%
• 更快的分析速度：构建分析耗时减少 57%
• 更快的增量构建：减少重构建过程中的分析开销，HMR 耗时降低约 47%
• 改进多 compiler 支持：在同一份报告中查看多个 compiler 的分析结果

#面向 agent 的构建分析

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

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

在 2.0 中，Agent CLI 成为推荐的自动化分析方式。配合 Rsdoctor analysis skill，agent 可以根据任务选择查询命令并分析结果。首先，在项目中安装 Agent CLI，也可以为 agent 安装配套的 skill：

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

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

接下来，在 Rsdoctor 插件中配置 brief 模式，生成供 agent 查询的 rsdoctor-data.json：

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

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

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

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

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

随着 agent 的分析入口统一到 Agent CLI，我们在 Rsdoctor 2.0 中下线了原有的 MCP Server 用法。使用 @rsdoctor/mcp-server 的项目可以参考 2.0 迁移指南完成迁移。

#更小的安装体积

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

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

#更快的分析速度

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

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

#更快的增量构建

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

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

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

#改进多 Compiler 支持

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

Rsdoctor 会自动将多个 compiler 的分析结果聚合到一份报告中。你可以通过 compiler 名称切换查看各自的结果，无需在多份报告之间来回查找。插件创建的 child compiler 也会被自动识别，并与 main compiler 的数据分开展示。

这些能力默认开启。如果需要自定义报告分组，例如将 SSR 项目的客户端和服务端构建归为一组，可以为插件实例指定相同的分组名称：

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

同一进程中的 compiler 若属于互不相关的构建，也可以通过 multiCompiler: false 关闭自动聚合。Agent CLI 同样支持选择 compiler，让 agent 针对指定构建进行分析。

#产物分析界面改进

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

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

优化前

优化后

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

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

相关 PR：#1705、#1782、#1830、#1839。

#如何升级

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

• 运行环境：要求 Node.js ^20.19.0 || >=22.12.0 和 Rspack 2.0 及以上版本。
• 包名与模块格式：使用 @rsdoctor/core 替换 @rsdoctor/rspack-plugin，并使用 ESM 导入。
• AI 工作流：从已移除的 @rsdoctor/mcp-server 迁移到 Agent CLI。
• Rsdoctor 2.0 不再兼容 webpack，使用 webpack 的项目可以继续使用 Rsdoctor 1.x。

完整的升级步骤、配置变更和验证方法，请参考 Rsdoctor 2.0 升级指南。指南也提供了迁移 skill，可让 agent 协助完成升级。

欢迎试用 Rsdoctor 2.0 并分享反馈，完整更新内容见 release 页面。

#致谢

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