> 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 Rsdoctor 2.0 围绕 Rspack 收敛了包结构。大多数项目只需要安装 `@rsdoctor/core`。此版本移除了多个独立包。请同时更新依赖和导入路径，避免在 2.0 代码中解析到 1.x 包。 推荐使用 [`rsdoctor-migrate-v2` Skill](https://github.com/rstackjs/agent-skills/pull/115)，让编码 Agent 检查项目、执行适用的迁移步骤并验证结果： ```bash npx skills add rstackjs/agent-skills --skill rsdoctor-migrate-v2 ``` ## 检查构建工具 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`： ```bash pnpm remove @rsdoctor/rspack-plugin pnpm add -D @rsdoctor/core ``` Rsdoctor 2.0 的包仅提供 ESM 产物。请在现有 ESM 导入中更新包路径： ```ts title="迁移前" import { RsdoctorRspackPlugin } from '@rsdoctor/rspack-plugin'; ``` ```ts title="迁移后" 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` 使用相同版本： ```bash pnpm add -D @rsdoctor/core @rsdoctor/cli ``` 原有命令和 Node.js API 继续保留，当前用法请参考 [CLI 使用教程](/zh/guide/start/cli.md)。 ## AI 工作流迁移 Rsdoctor 2.0 已移除 `@rsdoctor/mcp-server`，不再提供 MCP Server。所有基于 Rsdoctor 的 AI 辅助分析工作流都需要迁移到 `@rsdoctor/agent-cli`： ```bash 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 直接读取该文件： ```bash 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](/zh/guide/start/ai.md)。 ## 配置迁移 \{#configuration-migration} **Rsdoctor 1.x 引入了 Rsdoctor 2.x 使用的 output 配置。** 与旧版配置相比，新配置更易于使用和扩展。 顶层 `mode`、`port`、`brief` 和旧版 `output.compressData` 配置已在 Rsdoctor 2.x 中移除且会被忽略。请根据下表迁移这些配置。两种 `features` lite 配置仍受支持，下表仅列出其等价的 `output` 配置。 | 原配置 | 新配置 | | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | mode | 改为配置 `output.mode`。 | | port | 改为配置 `server.port`。 | | brief | 改为配置 `output.mode: 'brief'`，并将 `output.options.type` 设置为 `['html']`。将 `brief.reportHtmlName` 迁移至 `output.options.htmlOptions.reportHtmlName`。 | | output.compressData | 改为配置 `output.mode: 'brief'`，并将 `output.options.type` 设置为 `['json']`。 | | `mode: 'lite'` | 改为配置 `output.mode: 'normal'`，并将 `output.reportCodeType` 设置为 `noCode` 或 `noAssetsAndModuleSource`。 | | `features: { lite: true }` 或 `features: ['lite']` | 仍受支持。等价的 `output` 配置为 `output.mode: 'normal'`，并按上一行设置 `output.reportCodeType`。 | | 无 | 新增 `output.options.jsonOptions.sections` 配置 | ### 配置改动详情 #### mode 顶层 `mode` 配置已在 Rsdoctor 2.x 中移除。请使用 `output.mode` 统一管理输出相关配置。 ```js title="迁移前" new RsdoctorRspackPlugin({ mode: 'normal', }); ``` ```js title="迁移后" new RsdoctorRspackPlugin({ output: { mode: 'normal', }, }); ``` #### port 顶层 `port` 配置已在 Rsdoctor 2.x 中移除。请将端口配置移至 `server.port`。 ```js title="迁移前" new RsdoctorRspackPlugin({ port: 3001, }); ``` ```js title="迁移后" 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`。 ```js title="迁移前" new RsdoctorRspackPlugin({ mode: 'brief', brief: { reportHtmlName: 'build-report.html', }, }); ``` ```js title="迁移后" 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']`。 ```js title="迁移前" new RsdoctorRspackPlugin({ output: { compressData: true, }, }); ``` ```js title="迁移后" 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` 配置能更清晰地表达需要包含的报告内容。 ```js title="迁移前" new RsdoctorRspackPlugin({ mode: 'lite', }); ``` ```js title="迁移后" new RsdoctorRspackPlugin({ output: { mode: 'normal', reportCodeType: 'noAssetsAndModuleSource', }, }); ``` #### output.options.jsonOptions.sections 使用 `output.options.jsonOptions.sections` 控制 JSON 输出包含的数据分区。可配置字段请参阅 [output.options.jsonOptions.sections](/zh/config/options/output.md#options)。 ```js new RsdoctorRspackPlugin({ output: { mode: 'brief', options: { type: ['json'], jsonOptions: { sections: { moduleGraph: false, chunkGraph: true, }, }, }, }, }); ``` ## 验证升级结果 更新依赖和导入路径后： 1. 搜索项目中是否仍存在已移除的包名： ```bash rg '@rsdoctor/(rspack-plugin|webpack-plugin|sdk|graph|types|utils|components|mcp-server)' ``` 2. 使用项目的包管理器重新安装依赖。 3. 执行生产环境构建，确认 Rsdoctor 能够生成报告。 4. 打开报告，检查项目使用的概览、编译分析和产物分析页面。 5. 如果项目使用 `@rsdoctor/cli` 或 `@rsdoctor/agent-cli`，请使用新生成的 Rsdoctor 数据执行对应命令。