#Incremental

incremental 用于控制 Rspack 的增量构建能力。开启后，Rspack 会在重构建和热模块替换（HMR）过程中复用未受影响的中间结果，只重新计算受变更影响的阶段和产物，从而降低重构建和 HMR 的耗时。

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

#配置方式

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

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

#配置示例

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

export default {
  incremental: 'advance',
};

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

export default {
  incremental: {
    silent: false,
    modulesCodegen: false,
  },
};

#类型定义

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;
};

#性能影响

增量构建主要用于优化已有编译状态下的重构建和 HMR，对没有任何可复用状态的首次构建不会带来性能提升。

当启用并命中持久化缓存时，Rspack 可以从缓存中恢复部分构建状态，因此首次启动后的编译也可能受益于增量构建。

下表概述了不同场景下增量构建的效果：

表中的“热”表示存在可复用的编译状态或持久化缓存，“冷”表示没有可复用状态。