> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt.

# FAQ

## 如何只使用 Rsdoctor 的某个功能？

当**只需要** Rsdoctor 内的 [Bundle Size](/zh/guide/usage/bundle-size.md) 分析产物大小功能时，可以在 Rsdoctor 插件配置时添加对应的 [features](/zh/config/options/features.md) 配置项，参考下方代码：

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

new RsdoctorRspackPlugin({
  features: ['bundle'], // 代表只开启 bundle size 的功能分析
});
```

## Loader 耗时数据不准？

Rsdoctor 提供的 Loader 耗时是**预估耗时**。无法统计到准确耗时是因为 Loader 执行可能是**异步**函数也可能是**同步**函数，打包工具会**并行执行多个**不冲突的 Loader 函数，而 **JavaScript 是单线程**的，多个 Loader 函数均可能**抢占当前的任务队列**，且 Loader 函数内的**异步逻辑无法识别**，导致单个 Loader 函数在执行过程中**可能横跨**多个其他 Loader 的执行过程，因此会存在如下图所示的三种情况：

![](https://assets.rspack.rs/others/assets/rsdoctor/loader-cases.jpeg)
因此，Rsdoctor 提供的 Loader 耗时是一个**预估**的数据，我们给出的耗时数据准确反映了上图中情况 1 和情况 2，对于情况 3 的解决方案，我们目前还在探索中。

## 使用 `Rsdoctor` 构建时出现了 `out of memory` 问题

如果出现了 `out of memory` 的报错，可以尝试下列两个方法，推荐优先使用第一个：

### 方法一

增大 Node.js 内存上限，例如：`NODE_OPTIONS=--max-old-space-size=8096`。

### 方法二

这个问题通常是因为构建过程中存储源码信息，导致内存超限。请将 `output.reportCodeType` 设置为 `noCode` 或 `noAssetsAndModuleSource`，以降低内存占用。详情请参阅 [output.reportCodeType](/zh/config/options/output.md#reportcodetype)。

## 产物分析中，Module 都没有 Bundled/Parsed size 怎么办？

### 问题说明

`Source Size` 和 `Bundled Size` 的区别：

- **Source Size**：Module 文件源码的原始大小（如下图青色标识）。
- **Bundled Size**：经过打包及压缩后的 Module 的最终代码大小（如下图蓝色标识）。\\
- **Gzip Size**：经过 gzip 压缩后的 Module 的最终代码大小（如下图黄色标识）。

![](https://assets.rspack.rs/others/assets/rsdoctor/all-in-one-after.png)
### 解决方案

如果只有 Source Size，没有 Bundled Size，或者 **Tree Map 中没有 Module 下钻**（即没有 Modules 分块），则需要**手动开启 SourceMap**。**注意只在 Rsdoctor 开启时打开 SourceMap，不要影响线上产物**。

- 下面情况就需要手动开启 Sourcemap

![](https://assets.rspack.rs/others/assets/rsdoctor/all-in-one-before.png)
配置示例：

```js rspack.config.mjs
export default {
  devtool: 'cheap-source-map', // 或其他 devtool 配置
};
```

Rsdoctor 支持以下 SourceMap 配置：

- source-map
- hidden-source-map
- inline-source-map
- cheap-source-map
- cheap-module-source-map
- nosources-source-map

## 产物分析界面没有 `Bundled Size` 怎么办？

### 问题说明

`Source Size` 和 `Bundled Size` 的区别：

- **Source Size**：Module 文件源码的原始大小（如下图紫色标识）。
- **Bundled Size**：经过打包及压缩后的 Module 的最终代码大小（如下图青色标识）。

![](https://assets.rspack.rs/others/assets/rsdoctor/bundle-size-overall.png)
### 原因分析

当 [optimization.concatenateModules](https://rspack.rs/zh/config/optimization#optimizationconcatenatemodules) 配置为 `true` 时，Rsdoctor 无法通过 `acorn` 解析产物来分解出每个 **Module** 的实际代码大小，因此无法显示 `Bundled Size`。

### 解决方案

:::danger
**重要提醒：** 必须判断 `RSDOCTOR` 环境变量，不能直接修改 ConcatenateModules！线上环境默认开启 ConcatenateModules，线上构建环境中关闭会导致产物体积变大。
:::

**在开启 Rsdoctor 分析时，配置 concatenateModules 为 false**，如下所示。**同时要注意，关闭 concatenateModules 一定会导致产物体积略微变大，与线上环境的体积有一些差异。**

```js rspack.config.mjs
export default {
  optimization: {
    concatenateModules:
      process.env.NODE_ENV === 'production' && !process.env.RSDOCTOR, // 需要判断 RSDOCTOR 环境变量，不可以直接修改 concatenateModules！
  },
};
```

- rspeedy 项目中，在 `rspeedy.config.ts` 中配置：

```js rspeedy.config.ts
export default {
  tools: {
    rspack(config, { env }) {
      if (process.env.RSDOCTOR === 'true') {
        config.optimization = {
          ...config.optimization,
          concatenateModules: false,
        };
        return config;
      }
    },
  },
};
```

## CssExtractRspackPlugin 的 loader 耗时过长问题

在使用 Rsdoctor 对 Rspack 项目进行编译耗时分析时，可能会发现 [CssExtractRspackPlugin](https://rspack.rs/plugins/rspack/css-extract-rspack-plugin) 的 loader 耗时较长。然而，这个数值并不代表 CssExtractRspackPlugin 的 loader 的真实耗时，它还包含了对本模块编译的其他 loader 的耗时。

- 原因：[CssExtractRspackPlugin](https://rspack.rs/plugins/rspack/css-extract-rspack-plugin) 中的 loader 在 pitch 阶段会异步调用其他 loader，并等待这些 loader 执行后的回调结果。因此，CssExtractRspackPlugin 的耗时实际上包括了其他 loader 的执行时间和空闲时间。

![](https://assets.rspack.rs/rsdoctor/css-extract-loader.png)
## 在 Re.Pack 或自定义 Bundle 扩展名项目中使用 Rsdoctor

Rsdoctor 现在支持标准 `.js` 扩展名之外的自定义 JavaScript bundle 文件扩展名。这对于使用 `.bundle` 扩展名的 Re.Pack 等项目特别有用。

### 支持的扩展名

默认情况下，Rsdoctor 识别以下 JavaScript bundle 扩展名：

- `.js` - 标准 JavaScript 文件
- `.bundle` - Re.Pack 和其他自定义打包工具

### 无需配置

如果您的项目生成带有 `.bundle` 扩展名的 bundle 文件（例如 `main.bundle`、`vendor.bundle`），Rsdoctor 将自动：

- 解析和分析 `.bundle` 文件以及 `.js` 文件
- 在 Bundle 分析图表中显示 `.bundle` 文件
- 在 JavaScript 资源统计中包含 `.bundle` 资源
- 支持 `.bundle` 文件的 source map 分析

### 工作原理

检测逻辑已在以下领域更新：

1. **Bundle 解析**：`parseBundle` 函数现在在分析 bundle 内容时接受 `.js` 和 `.bundle` 扩展名。
2. **资源过滤**：资源摘要和过滤函数将 `.bundle` 文件视为 JavaScript 资源。
3. **文件类型检测**：所有文件扩展名匹配工具都包含 `.bundle` 作为公认的 JavaScript 扩展名。

### 用例示例

Re.Pack 项目通常生成带有 `.bundle` 扩展名的 bundle：

```
dist/
  ├── index.bundle        ← 现已支持！
  ├── vendor.bundle       ← 现已支持！
  ├── styles.css
  └── assets/
```

Rsdoctor 将自动检测和分析这些 `.bundle` 文件，无需任何额外配置。