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

# Incremental

`incremental` 控制 Rspack 是否在同一个长生命周期 compiler 的多次 compilation 之间复用未受影响的中间结果。它面向开发期重建、watch 模式和热模块替换（HMR）：Rspack 已知发生变化的文件，因此可以避免重新计算未受影响的阶段和产物。

Incremental 仅在 `mode` 设置为 `'development'` 时启用。独立的 `rspack build` 是一次性构建，没有可供更新的上一次 compilation，因此 `incremental` 不会让多次独立的 build 命令变成增量构建。

- **类型：** `boolean | 'none' | 'safe' | 'advance' | 'advance-silent' | Incremental`
- **默认值：** `'advance-silent'`

:::tip
增量 Artifact 与 [`cache`](https://rspack.rs/zh/config/cache.md) 相互独立。关闭缓存不会禁用开发、watch 或 HMR 场景中的增量重建。
:::

## 与 Cache 的关系

[`cache`](https://rspack.rs/zh/config/cache.md) 和 `incremental` 是两个相互独立的配置。Cache 将细粒度的计算结果保存在内存或基于文件系统的持久化存储中；Incremental 则从同一个 compiler 的上一次 compilation 中恢复上一轮 pass 的 Artifact，再根据已知 mutations 更新受影响的工作。

四种组合都有效：

| Cache | Incremental | 行为                                                                              |
| ----- | ----------- | ------------------------------------------------------------------------------- |
| 关闭    | 关闭          | 不通过 Cache 或 Incremental 复用上一次 compilation 或 build 的状态；compilation 内部的局部优化仍可能生效。 |
| 开启    | 关闭          | 不恢复 Artifact，但具体计算仍然可以命中 Memory Cache 或 Persistent Cache。                       |
| 关闭    | 开启          | 开发期重建恢复上一轮 pass 的 Artifact，以复用其中未受影响的部分，但不会读取或写入细粒度 Cache entry。                |
| 开启    | 开启          | 开发期重建同时使用上一轮 Artifact 恢复和细粒度 Cache 命中，是常规的高性能开发组合。                              |

Cache “开启”包括 `cache: true`、`cache: { type: 'memory' }` 和
`cache: { type: 'persistent' }`。

Rspack Incremental 的优化目标与 webpack 的
[`cacheUnaffected`](https://webpack.js.org/configuration/cache/#cachecacheunaffected) 类似：避免重新计算不受变更影响的工作。Rspack 将这一思路扩展到多个 compilation 阶段，并将其设计为独立于 Cache 的顶层能力。这是语义对齐，并不代表配置结构等价：webpack 要求 `cacheUnaffected` 与 Memory Cache 一起使用，而 Rspack 将 `incremental` 作为独立的顶层配置。

## 配置方式

`incremental` 支持预设值和对象两种配置方式。

大多数项目可以使用默认值；只有在需要关闭增量构建、回退到更保守的策略，或定位增量构建相关问题时，才需要显式配置。

| 配置                          | 行为                                                                      |
| --------------------------- | ----------------------------------------------------------------------- |
| `false` / `'none'`          | 禁用增量构建，不对任何阶段启用增量能力。                                                    |
| `'safe'`                    | 仅启用 `buildModuleGraph`、`buildChunkGraph` 和 `emitAssets` 阶段的增量能力。        |
| `true` / `'advance-silent'` | 启用所有增量阶段，并静默处理不利于增量构建的情况。这是 Rspack 的默认行为。                               |
| `'advance'`                 | 与 `'advance-silent'` 启用相同的增量阶段，但会在遇到不利于增量构建的配置或插件行为时输出警告，便于定位影响增量效果的原因。 |

## 配置示例

默认情况下无需显式配置 `incremental`。如果希望在开发过程中发现哪些配置或插件行为会导致增量阶段被关闭，可以使用 `'advance'`：

```js title="rspack.config.mjs"
export default {
  mode: 'development',
  incremental: 'advance',
};
```

也可以通过对象形式配置 `incremental`，对每个构建阶段的增量能力进行细粒度控制。对象配置主要用于调试或临时规避问题，常规场景推荐使用预设值。

使用对象配置时，省略的阶段选项默认值都是 `true`，`silent` 的默认值也是 `true`。例如，
`{ modulesCodegen: false }` 只会关闭该阶段，其他 Incremental 阶段仍然保持开启。

```js title="rspack.config.mjs"
export default {
  incremental: {
    silent: false,
    modulesCodegen: false,
  },
};
```

## 类型定义

```ts
type Incremental = {
  // 是否静默处理不利于增量构建的情况；设置为 false 时会输出警告
  silent?: boolean;
  // 以下配置用来控制各个阶段的增量是否开启
  buildModuleGraph?: boolean;
  finishModules?: boolean;
  optimizeDependencies?: boolean;
  buildChunkGraph?: boolean;
  optimizeChunkModules?: boolean;
  moduleIds?: boolean;
  chunkIds?: boolean;
  modulesHashes?: boolean;
  modulesCodegen?: boolean;
  modulesRuntimeRequirements?: boolean;
  chunksRuntimeRequirements?: boolean;
  chunksHashes?: boolean;
  chunkAsset?: boolean;
  emitAssets?: boolean;
};
```

## 性能影响

Incremental 只会在存在上一次 compilation 和明确变更集合时加速重建与 HMR，不会让首次 compilation 或独立的一次性 build 变成增量构建，但首次 compilation 仍会为后续重建准备 Artifact。

Memory Cache 或 Persistent Cache 可以独立加速首次构建和重建中的具体计算。尤其是进程启动后命中的 FileSystem Cache 属于 Cache 加速，而不是增量构建。