> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt.
# Bundle diff
Version: 0.4.5
我们提供了 Bundle Diff 的功能，可以让你进行对比分析两次构建产物发生的变化。
目前我们提供了以下几种使用方式：
- [通过 CLI 在本地打开报告](/zh/guide/start/cli.md)
- [通过 CLI 生成 JSON 报告](#通过-cli-生成-json-报告)
- 在线上传分析（计划支持）
## 使用方式
### 通过 CLI 在本地打开报告
首先你需要准备 **2 份** Rsdoctor 产出的[manifest.json](/zh/config/options/term.md#manifestjson)，然后通过安装[@rsdoctor/cli](/zh/guide/start/cli.md#%E5%AE%89%E8%A3%85-rsdoctorcli) 并使用 CLI 提供的 `bundle-diff` 命令，详见[命令使用教程](/zh/guide/start/cli.md#bundle-diff-%E5%91%BD%E4%BB%A4)。
### 通过 CLI 生成 JSON 报告
使用 `--json [path]` 可以直接生成结构化差异报告，而不会启动报告服务器或打开浏览器：
```bash
rsdoctor bundle-diff \
--baseline="baseline/.rsdoctor/manifest.json" \
--current="current/.rsdoctor/manifest.json" \
--json="result.json"
```
如果省略 `--json` 后的路径，报告将保存为 `rsdoctor-diff.json`。报告包含 `assets`、`modules` 和 `packages` 的差异数据，可用于 CI 流程或生成 Pull Request 评论。
### 在线上传分析（计划支持）
我们计划提供了一个在线页面用于 Bundle Diff 分析，你可以通过在页面中上传 **2 份** Rsdoctor 产出的[manifest.json](/zh/config/options/term.md#manifestjson)，其中一份作为基准（Baseline），另一份则作为当前产物结果 (Current)，通过点击 Start Diff 则就可以进入我们的分析页面。
## 使用指南
### 功能概览
在 Bundle Diff 模块，你可以看到两次产物结果的信息对比，其中包含:
- **总体积变化**
- **不同类型文件的体积变化**
- **首屏资源的体积变化**
- **重复包的数量变化**
- **NPM Packages 的数量变化** 等信息
除了上面的数据变化概览之外，我们还能通过页面下方的**详情列表**模块，进行更深入的数据查询分析。
### 名词释义
| 名词 | 描述说明 |
| -------------------------------- | ---------------------------------------------------------------------- |
| Baseline | 代表作为**基准的数据源** |
| Current | 代表当前需要**与 Baseline 进行对比的目标数据源** |
| Asset / Assets | 代表当前**产物文件** |
| Bundle Size | 代表产物中**所有文件**的体积 |
| Total JS | 代表产物中所有 `.js` 文件的体积 |
| Initial JS | 代表产物中所有**首屏**加载的 `.js` 文件的体积 |
| Total CSS | 代表产物中所有 `.css` 文件的体积 |
| Initial CSS | 代表产物中所有**首屏**加载的 `.css` 文件的体积 |
| Image | 代表产物中所有 `.png`/`.jpg`/`.svg`/`.webp`/`.jpeg`/`.gif`/`.bmp` 的文件体积 |
| Font | 代表产物中所有 `.ttf`/`.fnt`/`.fon`/`.otf` 的文件体积 |
| Media | 代表产物中所有 `.mp3`/`.mp4`/`.avi`/`.wav`/`.flv`/`.mov`/`.mpg`/`.mpeg` 的文件体积 |
| HTML | 代表产物中所有 `.html` 的文件体积 |
| Duplicate Packages | 代表产物中存在的**重复包总数** |
| Modules | 代表产物中 Module 总数 |
| Packages | 代表产物中存在的 **NPM Packages 总数** |
| New | 代表**新增**，即 **Baseline 中不存在，Current 中存在** |
| Deleted | 代表**移除了**，即 **Baseline 中存在，Current 中不存在** |
| Changed | 代表**只发生了内容改变**，即 **Baseline 和 Current 中都存在**，但是**内容变化**了 |
| Parsed Size | 代表**打包进产物的最终体积** |
### 使用说明
#### Dashboard
在页面顶部，我们可以看到很多数据由不同的卡片组成，其中包含了如下信息：
- **Bundle Size** 包含了两次产物总体积以及变化幅度。
- **Total JS | Initial JS** 包含了两次产物中 所有 JS 与 首屏 JS 的总体积以及变化幅度。
- **Total CSS | Initial CSS** 包含了两次产物中 所有 CSS 与 首屏 CSS 的总体积以及变化幅度。
- **Image | Font | Media** 包含了图片、字体、音频类文件的体积以及变化幅度。
- **HTML** 包含了 html 文件的体积以及变化幅度。
- **Others** 代表除了上述文件外的其他所有文件的体积以及变化幅度。
- **Duplicate Package** 代表两次产物中存在的重复包数量，点击则可以查看对应的重复包详情。
- **Modules** 代表两次产物中存在的 Modules 数量。
- **Packages** 代表两次产物中存在的 NPM Packages 总数，以及新增、删除、变更的数量变化。
#### Overview
在 Overview 模块中，我们可以看到不同**文件类型维度**的**体积**、**数量**以及**变化幅度**。
#### Assets
:::tip
Rsdoctor 在展示 Asset 名称时，会尝试移除产物文件名中的 hash 值，以方便进行产物文件对比。
:::
在 Assets 模块中，我们可以看到产物文件之间的**体积**以及**变化幅度**。
同时**点击**列表项目前的 **"+" 按钮**，则可以展开看到对应 Asset 所**包含的模块列表**（即 `Modules of "***"`），其中则会显示模块之间的**体积**以及**变化幅度**。
Rsdoctor 会**兼容同名 Assets 文件 hash 不同**的情况，但是对于**拆包产生的命名不同的 Assets**，Rsdoctor 则无法辨别其比较对象。
所以 Rsdoctor Assets 模块**还提供了 select 组件**，你可以**手动选择想要对比的 Assets 资源**。
#### Modules
在 Modules 模块中，我们可以看到两次产物中包含的所有模块的**名称**、**体积**以及**变化幅度**。
其中 `New` / `Deleted` / `Changed` 标签则代表模块在 `Current` 中到底是 新增 还是 被删除 或者只是发生了改变。
而 `node_modules` 标签则意味着该模块的路径中包含了 `/node_modules/`。
在列表项的右侧，则可以通过对应的「View Changes」按钮来查看模块代码的变更。
**代码对比，分几种数据：**
- **Source Code: 源码数据。** `Normal` 模式下存在代码资源，`Lite` 模式下不存在代码资源，`Brief` 模式不存在代码资源。
- **Bundled Code: 构建后代码。** `Normal` 模式下存在代码资源，`Lite` 模式下存在代码资源，`Brief` 模式不存在代码资源。
#### Packages
在 Packages 模块，我们可以看到两次产物中包含的**所有 NPM Packages 列表**，每个列表项则会包含其对应的 **Package Name**、**Version（版本号）**、**Parsed Size（打包后的最终体积）**。
