Rsdoctor 1.0：Rspack/webpack 生态的一站式构建分析利器

前端构建慢、产物莫名变大、某个依赖”不知道为什么被打进来了”——这些问题在 webpack 时代就存在，只是过去的分析工具各管一段：webpack-bundle-analyzer 看产物体积，speed-measure-webpack-plugin 量 loader/插件耗时，Statoscope 看资源。字节跳动开源的 Rsdoctor 想把这些合并成一个可视化工作台，并在 Rspack 崛起的背景下补上”Rspack 原生分析”这块空白。2025 年 3 月 19 日，Rsdoctor 发布 1.0。

本文基于其 1.0 发布公告与官方文档，拆解它解决什么问题、1.0 带来了什么，以及那些数字背后的口径。

一、背景：现有工具的三个不足

官方在公告里直接点名了三类前辈工具，并指出它们的盲区：

官方总结的三点痛点：分析不够深入（想看 loader 内部编译细节得手动调试）、功能局限（只给产物数据、不主动预警、不能自定义规则）、Rspack 支持不足（老工具分析不了 Rspack 的内置 loader）。

二、它是什么

Rsdoctor 自我定位是”为 Rspack 生态量身打造、同时完全兼容 webpack”的一站式构建分析工具。它不挑上层框架——只要构建底层是 Rspack 或 webpack，就能接：官方列举了 Docusaurus、Rspeedy(Lynx)、Storybook、Next.js、Nuxt、Re.Pack、Modern.js、Rsbuild、Rspress、Rslib 等。

它有两种用法定位：一是构建分析工具，把构建全过程可视化；二是可扩展分析工具，支持自定义扫描规则。

数据上，官方称自 2024 年开源后 npm 周下载量突破 10 万，已在字节内部大规模使用，并被 Sentry、NocoBase、Grafana 等项目采用，还被集成进 Docusaurus、Lynx。

三、五个典型场景

公告列了五个高频问题，对应 Rsdoctor 的能力：

1. 构建太慢？ → Loader 时序图看每个 loader、每个文件的编译耗时；
2. 构建结果不符预期？ → Loader Details 对比单个文件编译前后的 Input/Output；
3. 怎么合理分包？ → 产物分析里看 Modules 树，配合 splitChunks；
4. 产物为什么变大？ → Bundle Diff 对比两次 commit 的产物与依赖变化；
5. 某模块为什么被打进来？ → Modules 树里点 Module Graph 看上游依赖链。

上面这张官方 Loader Timeline 截图很能说明问题：横轴是时间，纵轴是各个 loader（babel-loader、mini-css-extract-plugin、postcss-loader、css-loader），悬停某个色块能看到该 loader 处理某个具体文件（如 myapp/src/routes/index.tsx）的开始/结束时间与耗时（示例里 duration: 20ms）。这正是传统工具要靠手动打断点才能看到的粒度。

Loader Details 页把同一文件编译前（Input）与编译后（Output）左右并置——右边能看到 @okuee/react 被 loader 改写成了带 __Button 别名和 components/button 样式引入的形式。当你怀疑某个 loader 改坏了样式或运行时行为时，这个 diff 直接给出答案。

四、1.0 的新特性

1. UI 全面升级：视觉与导航重做；
2. 分析效率提升：这是唯一带数字的特性——把耗时的数据处理逻辑用 Rust 重写并集成进 Rspack，官方称整体分析时间减少 20% 以上，通过 experiments.enableNativePlugin: true 开启；
3. 模块搜索：Bundle Size 页可按模块名快速定位其所在 chunk；
4. 新增扫描规则：
   • 跨 chunks 重复包检测：扫描不同 chunk 里重复打进的同一个包（导致体积膨胀）；
   • ECMA 版本检测：检查产物里是否出现了目标环境不支持的高级语法，可配置 ecmaVersion。

配置示例：

new RsdoctorRspackPlugin({
  experiments: { enableNativePlugin: true },
  linter: {
    rules: {
      'ecma-version-check': ['Warn', { ecmaVersion: 2015 }],
    },
  },
});

从 0.4 升级到 1.0 有少量不兼容：插件配置里的 reportCodeType、reportDir 被移到 output 下。

五、口径批判与官方自认的不足

把公告里的数字和”下一步”对照着看，有几处需要读者清醒：

1. “分析时间减少 20% 以上”是相对开启原生插件前后，且是官方在自家大型项目上测得。它同时承认：在大型项目里启用 Rsdoctor 本身会增加整体构建时间——原生插件只是把这个增量压小，不是消除。小项目可能根本感知不到。
2. “对 Rspack 内置 loader 的分析还不够精确”——这是官方在”下一步”里自己写的。因为 Rspack 基于 Rust、多线程，当前 Rsdoctor 对内置 loader 的性能数据和编译行为洞察仍不精确，计划后续在 Native Plugin 基础上改进。换句话说，它最大卖点（Rspack 分析）恰恰是当前精度短板。
3. “周下载 10 万”不等于”生产环境广泛验证”：周下载量受 CI、demo、框架集成（Docusaurus/Lynx 内置）拉动，不能直接等同于大型团队日常构建流程的稳定性。
4. 它是分析工具而非优化工具：它告诉你瓶颈在哪、为什么变大，但不会自动帮你修分包、删重复包——动作仍要开发者自己做。
5. 数据丰富但学习成本高：官方在”下一步”里承认，海量构建数据对新用户有门槛，所以才计划加 AI 分析。这反过来说明 1.0 开箱即用地”看懂”需要一定经验。

六、优势与局限

优势：

1. 一个工具覆盖 loader 耗时、产物 diff、模块依赖图、重复包/ECMA 扫描，替代多个老工具；
2. 原生支持 Rspack，是 Rstack 生态里少见的第一方分析器；
3. Loader Details 的编译前后 diff，把”loader 到底改了什么”可视化，调试体验好；
4. 支持自定义 linter 规则，可接入团队自己的工程规范；
5. 1.0 起用 Rust 重写热点路径，分析开销下降。

局限：

1. 对 Rspack 内置 loader 的分析精度官方自认还不够；
2. 大型项目上开启它仍会拖慢构建，需手动开原生插件；
3. 数据维度多，新用户有学习曲线；
4. 1.0 有配置项不兼容（reportCodeType/reportDir 迁移）；
5. 它只定位问题，不自动修复，优化决策仍靠人。

七、谁该关注

• Rspack/Rsbuild 技术栈团队：目前对 Rspack 支持最好的构建分析器，几乎是首选；
• 受够了”产物突然变大”的维护者：Bundle Diff + 跨 chunk 重复包检测能直接定位劣化；
• 需要调试 loader 行为的人：Loader Details 的前后 diff 比打断点高效；
• 纯 webpack 老项目：它也兼容，但 webpack-bundle-analyzer 等成熟工具够用，迁移优先级不高；
• CI 防劣化需求：官方的 Rsdoctor CI Action 还在路线图上，现在要自己接 Bundle Diff。

参考来源

• Rsdoctor 1.0 发布公告（官方博客）
• Rsdoctor 官方文档
• Rsdoctor GitHub
• Koala 项目库条目：Rsdoctor