#迁移到 Rsdoctor 2.0

Rsdoctor 2.0 围绕 Rspack 收敛了包结构。大多数项目只需要安装 @rsdoctor/core。此版本移除了多个独立包。请同时更新依赖和导入路径，避免在 2.0 代码中解析到 1.x 包。

推荐使用 rsdoctor-v2-upgrade Skill，让编码 Agent 检查项目、执行适用的迁移步骤并验证结果：

npx skills add rstackjs/agent-skills --skill rsdoctor-v2-upgrade

#检查构建工具

Rsdoctor 2.0 要求使用 Node.js ^20.19.0 || >=22.12.0 和 Rspack 2.0 及以上版本，不再支持 Rspack 1.x。此外，Rsdoctor 2.0 不再支持 webpack，并移除了 @rsdoctor/webpack-plugin。

• Rspack 项目可以继续按照本文档迁移。
• webpack 项目应继续使用 Rsdoctor 1.x，或先迁移到 Rspack，再升级 Rsdoctor。

#更新 Rspack 插件

使用 @rsdoctor/core 替换 @rsdoctor/rspack-plugin：

pnpm remove @rsdoctor/rspack-plugin
pnpm add -D @rsdoctor/core

Rsdoctor 2.0 的包仅提供 ESM 产物。请在现有 ESM 导入中更新包路径：

import { RsdoctorRspackPlugin } from '@rsdoctor/rspack-plugin';

import { RsdoctorRspackPlugin } from '@rsdoctor/core';

如果 1.x 配置使用 CommonJS require()，请改为上面的 ESM 导入方式。

@rspack/core 仍是 @rsdoctor/core 的可选 peer dependency，最低支持版本为 2.0。基于 Rspack 的构建工具通常已经提供该依赖；直接使用 Rspack 的项目需要安装 @rspack/core。

Rsdoctor 2.0 使用 Rspack 内置的 Rsdoctor Native Plugin 收集 Module Graph 和 Chunk Graph。请移除原有的 experiments.enableNativePlugin 配置，因为该能力现在始终启用。如果构建提示 experiments.RsdoctorPlugin 不可用，请升级项目或框架提供的 Rspack 依赖。

#CLI 迁移

@rsdoctor/cli 仍是 rsdoctor 命令对应的包。请为 @rsdoctor/cli 和 @rsdoctor/core 使用相同版本：

pnpm add -D @rsdoctor/core @rsdoctor/cli

原有命令和 Node.js API 继续保留，当前用法请参考 CLI 使用教程。

#AI 工作流迁移

Rsdoctor 2.0 已移除 @rsdoctor/mcp-server，不再提供 MCP Server。所有基于 Rsdoctor 的 AI 辅助分析工作流都需要迁移到 @rsdoctor/agent-cli：

pnpm remove @rsdoctor/mcp-server
pnpm add -D @rsdoctor/agent-cli

Agent CLI 是新的替代工作流，但不兼容 MCP 协议，也不是旧 API 的直接替代品。不能只替换包名，还需要完成以下调整：

1. 从 .cursor/mcp.json、.vscode/mcp.json 等配置中删除 Rsdoctor MCP 项。

2. 删除启动 npx @rsdoctor/mcp-server 的脚本或自动化配置。

3. 生成 rsdoctor-data.json，然后使用 Agent CLI 直接读取该文件：

   rsdoctor-agent bundle optimize --data-file ./dist/rsdoctor-data.json
   rsdoctor-agent query packages_duplicates --data-file ./dist/rsdoctor-data.json

4. 调整 AI Agent 和自动化流程，通过 rsdoctor-agent 执行分析并消费其结构化 JSON 输出。支持 Skill 的 Coding Agent 可以使用 Rsdoctor analysis skill 管理此流程。

Agent CLI 直接读取数据文件，因此不再需要 MCP Server 端口、compiler 等 MCP 专用配置。安装、数据生成和更多命令示例请参考 AI。

#配置迁移

顶层 mode、port、brief 和旧版 output.compressData 配置已在 Rsdoctor 2.x 中移除且会被忽略。请根据下表迁移这些配置。两种 features lite 配置 仍受支持，下表仅列出其等价的 output 配置。

请从配置中移除 supports.banner。该选项已在 Rsdoctor 2.x 中删除，无需替代配置。

#配置改动详情

#mode

顶层 mode 配置已在 Rsdoctor 2.x 中移除。请使用 output.mode 统一管理输出相关配置。

new RsdoctorRspackPlugin({
  mode: 'normal',
});

new RsdoctorRspackPlugin({
  output: {
    mode: 'normal',
  },
});

#port

顶层 port 配置已在 Rsdoctor 2.x 中移除。请将端口配置移至 server.port。

new RsdoctorRspackPlugin({
  port: 3001,
});

new RsdoctorRspackPlugin({
  server: {
    port: 3001,
  },
});

#brief

顶层 brief 配置已在 Rsdoctor 2.x 中移除。当前 brief 简报模式同时支持 HTML 和 JSON 输出，相关配置统一收敛到 output.options。将原有的 brief 配置替换为 output.mode: 'brief'，并将 output.options.type 设置为 ['html']。将 brief.reportHtmlName 迁移至 output.options.htmlOptions.reportHtmlName。

new RsdoctorRspackPlugin({
  mode: 'brief',
  brief: {
    reportHtmlName: 'build-report.html',
  },
});

new RsdoctorRspackPlugin({
  output: {
    mode: 'brief',
    options: {
      type: ['html'],
      htmlOptions: {
        reportHtmlName: 'build-report.html',
      },
    },
  },
});

#output.compressData

output.compressData 已在 Rsdoctor 2.x 中移除且会被忽略。请将其替换为 output.mode: 'brief'，并将 output.options.type 设置为 ['json']。

new RsdoctorRspackPlugin({
  output: {
    compressData: true,
  },
});

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

#lite

lite 模式的内部逻辑等同于 output.reportCodeType 为 noCode 或 noAssetsAndModuleSource，主要是为了解决大项目在打开报告时过慢或者构建时 OOM 的问题。

mode: 'lite' 已在 Rsdoctor 2.x 中移除且会被忽略。请将其替换为 output.mode: 'normal'，并将 output.reportCodeType 设置为 noCode 或 noAssetsAndModuleSource。

features: { lite: true } 和 features: ['lite'] 均仍受支持，无需迁移。等价的 output.reportCodeType 配置能更清晰地表达需要包含的报告内容。

new RsdoctorRspackPlugin({
  mode: 'lite',
});

new RsdoctorRspackPlugin({
  output: {
    mode: 'normal',
    reportCodeType: 'noAssetsAndModuleSource',
  },
});

#output.options.jsonOptions.sections

使用 output.options.jsonOptions.sections 控制 JSON 输出包含的数据分区。可配置字段请参阅 output.options.jsonOptions.sections。

new RsdoctorRspackPlugin({
  output: {
    mode: 'brief',
    options: {
      type: ['json'],
      jsonOptions: {
        sections: {
          moduleGraph: false,
          chunkGraph: true,
        },
      },
    },
  },
});

#验证升级结果

更新依赖和导入路径后：

1. 搜索项目中是否仍存在已移除的包名：

   rg '@rsdoctor/(rspack-plugin|webpack-plugin|sdk|graph|types|utils|components|mcp-server)'

2. 使用项目的包管理器重新安装依赖。

3. 执行生产环境构建，确认 Rsdoctor 能够生成报告。

4. 打开报告，检查项目使用的概览、编译分析和产物分析页面。

5. 如果项目使用 @rsdoctor/cli 或 @rsdoctor/agent-cli，请使用新生成的 Rsdoctor 数据执行对应命令。