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

# Stats

打包信息：该选项可用于生成分析模块的依赖关系图，以及优化编译速度的打包信息。

:::info 输出打包信息的 JSON 文件

- 使用 `@rspack/cli`，`rspack build --json stats.json`。
- 通过 Rspack 的 JavaScript API，`stats.toJson(options)`、`stats.toString(options)`。

:::

- **类型：**

```ts
type StatsPresets =
  | 'normal'
  | 'none'
  | 'verbose'
  | 'errors-only'
  | 'errors-warnings'
  | 'minimal'
  | 'detailed'
  | 'summary';

type Stats = boolean | StatsOptions | StatsPresets;
```

- **`@rspack/core` 中的默认值：** `{}`
- **`@rspack/cli` 中的默认值：** `{ "preset":"errors-warnings", "timings":true, "logging":false }`

## 预设（Stats presets）

| 预设                  | 描述                                              |
| ------------------- | ----------------------------------------------- |
| `'normal'` (`true`) | 按照 stats options 的默认值输出                         |
| `'none'` (`false`)  | 不输出任何信息                                         |
| `'verbose'`         | 输出所有信息                                          |
| `'errors-only'`     | 只输出错误相关信息                                       |
| `'errors-warnings'` | 只输出错误和警告相关信息                                    |
| `'minimal'`         | 只在编译或者错误发生时输出                                   |
| `'detailed'`        | 输出除了 `chunkModules` 之外 `chunkRootModules` 的所有信息 |
| `'summary'`         | 只输出摘要                                           |

可以指定具体哪些打包信息进行输出，以下所有字段都是可选（optional）的。

## 预设选项

### stats.all


- 类型： `boolean`
- 默认值：`undefined`


控制所有 stats options 是否输出。

:::warning 警告
开启 `stats.all` 会导致大量的 Rust 与 JavaScript 的数据传输，这将显著提高 Stats 生成耗时，请谨慎使用。
:::

### stats.preset


- 类型： `boolean | StatsPresets`
- 默认值：`undefined`


按照[预设值](/zh/config/stats.md#预设stats-presets)进行输出，这在[扩展信息输出行为](/zh/config/stats.md#扩展信息输出行为)时很有用。

## 产物选项

### stats.assets


- 类型： `boolean`
- 默认值：`true`


是否输出产物相关信息，参考 [Asset 对象结构](/zh/api/javascript-api/stats-json.md#asset-对象结构)。

### stats.assetsSort


- 类型： `string`
- 默认值：`"id"`


基于指定的字段对产物排序。可用的排序字段见[字段排序](/zh/config/stats.md#字段排序)。使用 `!` 作为前缀可以反转排序结果。

### stats.assetsSpace


- 类型： `number`
- 默认值：`15`


展示的产物数量（超过的部分将以分组方式折叠）。

### stats.relatedAssets


- 类型： `boolean`
- 默认值：`false`


是否展示与产物相关的其他资源产物信息（如资源的 SourceMap 文件）。

### stats.excludeAssets


- 类型： `boolean | string | RegExp | ((name: string, asset: any) => boolean) | Array<string | RegExp | ((name: string, asset: any) => boolean)>`
- 默认值：`false`


隐藏匹配的资源，匹配方式支持字符串、正则，或接收资源名称和资源对象并返回布尔值的函数，同时也支持以上类型的数组。

### stats.cachedAssets


- 类型： `boolean`
- 默认值：`true`


是否展示被缓存的资源（若为 `false` 则只展示被生成的产物）。

## 产物分组选项

### stats.groupAssetsByChunk


- 类型： `boolean`


是否按照资源与 chunk 的关系分组。

### stats.groupAssetsByEmitStatus


- 类型： `boolean`


是否按照资源的状态分组（如被生成、被缓存等）。

### stats.groupAssetsByExtension


- 类型： `boolean`


是否按照资源的扩展名分组。

### stats.groupAssetsByInfo


- 类型： `boolean`


是否按照资源的信息分组（如 immutable、development、hotModuleReplacement 等）。

### stats.groupAssetsByPath


- 类型： `boolean`


是否按照资源的路径分组。

## Chunk 选项

### stats.chunks


- 类型： `boolean`
- 默认值：`true`


是否展示 Chunk 信息，参考 [Chunk 对象结构](/zh/api/javascript-api/stats-json.md#chunk-对象结构)。

### stats.chunkModules


- 类型： `boolean`
- 默认值：`true`


是否展示 Chunk 内包含的模块信息。

### stats.chunkModulesSpace


- 类型： `number`
- 默认值：`10`


展示的 Chunk 内模块数量（超过的部分将以分组方式折叠）。

### stats.chunkModulesSort


- 类型： `string`
- 默认值：`"name"`


基于指定的字段对 Chunk 内模块排序。可用的排序字段见[字段排序](/zh/config/stats.md#字段排序)。使用 `!` 作为前缀可以反转排序结果。

### stats.dependentModules


- 类型： `boolean`
- 默认值：`false`


是否展示 Chunk 内被其他模块所依赖的模块。

### stats.chunkOrigins


- 类型： `boolean`
- 默认值：`true`


是否展示 Chunk 的引入来源信息。

### stats.chunkRelations


- 类型： `boolean`
- 默认值：`false`


是否展示 Chunk 的父子、兄弟关联信息。

### stats.chunksSort


- 类型： `string`
- 默认值：`"id"`


基于指定的字段对 Chunk 排序。可用的排序字段见[字段排序](/zh/config/stats.md#字段排序)。使用 `!` 作为前缀可以反转排序结果。

### stats.ids


- 类型： `boolean`
- 默认值：`false`


是否展示模块 ID 和 Chunk ID。

## ChunkGroup 选项

### stats.chunkGroups


- 类型： `boolean`
- 默认值：`true`


是否展示 ChunkGroup 信息，参考 [ChunkGroup 对象结构](/zh/api/javascript-api/stats-json.md#entrychunkgroup-对象结构)。

### stats.chunkGroupAuxiliary


- 类型： `boolean`
- 默认值：`true`


是否展示 ChunkGroup 的辅助资源。

### stats.chunkGroupChildren


- 类型： `boolean`
- 默认值：`true`


是否展示子 ChunkGroup 相关信息（如预取 prefetched、预载 preloaded 的 ChunkGroup 信息）。

### stats.chunkGroupMaxAssets


- 类型： `number`
- 默认值：`5`


展示 ChunkGroup 的最大资源数量。

### stats.entrypoints


- 类型： `boolean | 'auto'`
- 默认值：`false`


是否展示 Entrypoint 相关信息，参考 [Entrypoint 对象结构](/zh/api/javascript-api/stats-json.md#entrychunkgroup-对象结构)。

当 `stats.entrypoints` 被设置为 `'auto'` Rspack 将自动决定是否在 stats 输出中展示入口信息。

## 模块选项

### stats.modules


- 类型： `boolean`
- 默认值：`true`


是否展示模块信息，参考 [Module 对象结构](/zh/api/javascript-api/stats-json.md#module-对象结构)。

### stats.moduleTrace


- 类型： `boolean`
- 默认值：`true`


是否展示模块错误/警告时的依赖链信息。

### stats.moduleAssets


- 类型： `boolean`
- 默认值：`true`


是否展示模块包含的资源信息。

### stats.modulesSpace


- 类型： `number`
- 默认值：`15`


展示的模块数量（超过的部分将以分组方式折叠）。

### stats.modulesSort


- 类型： `string`
- 默认值：`"id"`


基于指定的字段对模块排序。可用的排序字段见[字段排序](/zh/config/stats.md#字段排序)。使用 `!` 作为前缀可以反转排序结果。

### stats.reasons


- 类型： `boolean`
- 默认值：`true`


是否展示模块的引入来源信息。

### stats.reasonsSpace


- 类型： `number`
- 默认值：`1000`


展示的引入来源信息长度（超过的部分将以分组方式折叠）。

### stats.source


- 类型： `boolean`
- 默认值：`false`


是否展示模块的源码。

### stats.depth


- 类型： `boolean`
- 默认值：`false`


是否展示模块与入口模块的距离。

### stats.orphanModules


- 类型： `boolean`
- 默认值：`false`


是否展示孤立模块。

> 孤立模块指不被任何 Chunk 包含的模块。

### stats.runtimeModules


- 类型： `boolean`
- 默认值：`true`


是否展示运行时模块。

> 运行时模块为 Rspack 内置模块，用于提供各种运行时能力。

:::tip
`stats.runtime` 是 `stats.runtimeModules` 的兼容性别名。只有在没有指定 `stats.runtimeModules` 时才会生效；如果两者都设置，以 `stats.runtimeModules` 为准。
:::

### stats.cachedModules


- 类型： `boolean`
- 默认值：`true`


是否展示被缓存的模块。

:::tip
`stats.cached` 是 `stats.cachedModules` 的兼容性别名。只有在没有指定 `stats.cachedModules` 时才会生效；如果两者都设置，以 `stats.cachedModules` 为准。
:::

### stats.excludeModules


- 类型： `boolean | string | RegExp | ((name: string, module: any, type: any) => boolean) | Array<string | RegExp | ((name: string, module: any, type: any) => boolean)>`
- 默认值：`false`


隐藏匹配的模块，匹配方式支持字符串、正则，或接收模块名称、模块对象和模块类型并返回布尔值的函数，同时也支持以上类型的数组。

### stats.nestedModules


- 类型： `boolean`
- 默认值：`true`


是否展示嵌套在其他模块中的模块信息（如 ModuleConcatenation 合并前的模块信息）。

### stats.nestedModulesSpace


- 类型： `number`
- 默认值：`10`


展示的被嵌套模块数量（超过的部分将以分组方式折叠）。

### stats.nestedModulesSort


- 类型： `string`


基于指定的字段对嵌套模块排序。可用的排序字段见[字段排序](/zh/config/stats.md#字段排序)。使用 `!` 作为前缀可以反转排序结果。

## 模块分组选项

### stats.groupModulesByAttributes


- 类型： `boolean`


是否基于模块的属性分组（是否包含错误、是否包含警告、是否包含资源、是否必须、是否为孤立模块、是否为被依赖的模块等）。

### stats.groupModulesByCacheStatus


- 类型： `boolean`


是否基于模块的缓存状态分组（包括已缓存、已构建且可缓存）。

### stats.groupModulesByExtension


- 类型： `boolean`


是否基于模块的扩展名分组。

### stats.groupModulesByPath


- 类型： `boolean`


是否基于模块的路径分组。

### stats.groupModulesByType


- 类型： `boolean`


是否基于模块的类型分组。

### stats.groupModulesByLayer


- 类型： `boolean`


是否按模块的 layer 进行分组。

### stats.groupReasonsByOrigin


- 类型： `boolean`


是否基于来源模块对引入来源信息分组。

## Optimization 相关

### stats.providedExports


- 类型： `boolean`
- 默认值：`false`


是否展示模块的导出。

### stats.usedExports


- 类型： `boolean`
- 默认值：`false`


是否展示模块被使用的导出。

### stats.optimizationBailout


- 类型： `boolean`
- 默认值：`false`


是否展示模块优化失效的原因。

## 错误/警告选项

### stats.errors


- 类型： `boolean`
- 默认值：`true`


是否展示构建过程中产生的错误。

### stats.errorsCount


- 类型： `boolean`
- 默认值：`true`


是否展示错误的总个数。

### stats.errorDetails


- 类型： `boolean`
- 默认值：`false`


是否展示错误的详情。为 `'auto'` 时，若错误仅有两个及以下则将展示错误详情。

### stats.errorsSpace


- 类型： `number`
- 默认值：`5`


展示单个错误时的最大行数。

### stats.errorStack


- 类型： `boolean`
- 默认值：`true`


是否展示错误的堆栈信息。

### stats.warnings


- 类型： `boolean`
- 默认值：`true`


是否展示构建过程中产生的警告。

### stats.warningsCount


- 类型： `boolean`
- 默认值：`true`


是否展示警告的总个数。

### stats.warningsSpace


- 类型： `number`
- 默认值：`5`


展示的警告最大行数。

## 日志选项

### stats.logging


- 类型： `'info' | 'none' | 'error' | 'warn' | 'log' | 'verbose' | boolean`


是否展示 [`compilation.getLogger`](/zh/api/javascript-api/compilation.md#getlogger) 所记录的日志信息。

- `'none'`, `false`: 禁用日志
- `'error'`: 仅展示错误
- `'warn'`: 仅展示错误与告警
- `'info'`: 展示错误，告警与信息
- `'log'`, `true`: 展示错误，告警与信息，日志，分组，清理信息。被折叠的部分也会以折叠状态展示。
- `'verbose'`: 输出所有日志除了调试信息和堆栈信息。被折叠的部分也会以展开状态展示。

### stats.loggingDebug

- **类型：**

```ts
type FilterItemTypes = RegExp | string | ((value: string) => boolean);
type StatsLoggingDebug = boolean | FilterItemTypes | FilterItemTypes[];
```

是否展示插件和 loader 中指定 [Logger](/zh/api/javascript-api/logger.md) 的调试信息。当 `stats.logging` 为 `false` 时 `stats.loggingDebug` 会被忽略。

```js title="rspack.config.mjs"
export default {
  stats: {
    loggingDebug: [
      'MyPlugin',
      /rspack/, // 获取 Rspack 内部的日志
    ],
  },
};
```

### stats.loggingTrace


- 类型： `boolean`
- 默认值：`true`


是否展示堆栈信息。

### stats.colors

- **类型：**

```ts
type StatsColorOptions = {
  bold?: string;
  cyan?: string;
  green?: string;
  magenta?: string;
  red?: string;
  yellow?: string;
};

type StatsColors = boolean | StatsColorOptions;
```

- **默认值：** 根据当前环境决定

是否在展示日志时添加颜色。

当传入对象时，可以自定义每种支持颜色使用的 ANSI 转义序列。默认情况下，Rspack 会在当前环境支持颜色输出时启用颜色。

## Compilation 选项

### stats.hash


- 类型： `boolean`
- 默认值：`true`


是否展示本次构建的哈希。

### stats.env


- 类型： `boolean`
- 默认值：`false`


是否展示 `--env` 参数传入的信息。

### stats.builtAt


- 类型： `boolean`
- 默认值：`true`


是否展示构建的开始时间点。

### stats.version


- 类型： `boolean`
- 默认值：`true`


是否展示 Rspack 的版本号。

### stats.publicPath


- 类型： `boolean`
- 默认值：`true`


是否展示产物的[加载路径](/zh/config/output.md#outputpublicpath)。

### stats.outputPath


- 类型： `boolean`
- 默认值：`true`


是否展示产物的[输出路径](/zh/config/output.md#outputpath)。

### stats.children


- 类型： `boolean`
- 默认值：`true`


是否展示 childCompiler 的 stats 信息。

### stats.performance


- 类型： `boolean`
- 默认值：`true`


是否展示产物文件超过 [`performance.maxAssetSize`](/zh/config/performance.md#performancemaxassetsize) 配置时的提示信息。

### stats.timings


- 类型： `boolean`
- 默认值：`true`


是否展示本次构建的耗时。

## 字段排序

对于 `assetsSort`, `chunksSort` 和 `modulesSort` 它们有几个可用的字段用于排序：

- `'id'`: 是元素（指资源，Chunk 或模块，下同）的 id
- `'name'`: 元素的名称，在导引的时候被分配
- `'size'`: 元素的大小，单位字节（bytes）
- `'chunks'`: 元素来源于哪些 chunks（例如，一个 Chunk 有多个子 Chunk，子 Chunk 会被基于主 Chunk 组合到一起）
- `'errors'`: 元素中的错误数量
- `'warnings'`: 元素中的告警数量
- `'failed'`: 元素是否编译失败
- `'cacheable'`: 元素是否可被缓存
- `'built'`: 资源是否被构建
- `'prefetched'`: 资源是否可被预取
- `'optional'`: 资源是否可选
- `'identifier'`: 元素的标识符
- `'index'`: 元素处理顺序
- `'issuer'`: 上游（issuer）的标识符
- `'issuerId'`: 上游（issuer）的 ID
- `'issuerName'`: 上游（issuer）的名称
- `'issuerPath'`: 完整的上游（issuer）路径

## 扩展信息输出行为

如果你想使用预设的输出行为，但又想对个别字段进行自定义设置，可以在指定 `stats.preset` 或 `stats.all` 之后对字段的输出行为进行自定义。

举例来说，只输出错误和模块被引入的原因：

```js title="rspack.config.mjs"
export default {
  stats: {
    preset: 'errors-only',
    reasons: true,
  },
};
```


本页改编自 [webpack 文档](https://webpack.docschina.org/configuration/stats/)，遵循 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)，且已作修改。