> 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.

# Cache


[Added in v2.0.0](https://github.com/web-infra-dev/rspack/releases/tag/v2.0.0)

`cache` 选项用于控制 Rspack 的缓存策略，让 Rspack 可以在构建之间复用缓存数据以提升构建性能。

Rspack 支持两种启用状态的 Cache 存储模式：进程内的 Memory Cache，以及基于文件系统的 Persistent Cache。两者都用于存储细粒度计算结果，并且与 [`incremental`](https://rspack.rs/zh/config/incremental.md) 相互独立。

- **类型：**

```ts
type CacheOptions =
  | boolean
  | {
      type: 'memory';
    }
  | {
      type: 'persistent';
      name?: string;
      buildDependencies?: string[];
      version?: string;
      maxAge?: number;
      maxMemoryGenerations?: number;
      maxVersions?: number;
      portable?: boolean;
      readonly?: boolean;
      snapshot?: {
        immutablePaths?: Array<string | RegExp>;
        unmanagedPaths?: Array<string | RegExp>;
        managedPaths?: Array<string | RegExp>;
      };
      storage?: {
        type: 'filesystem';
        directory?: string;
        location?: string;
      };
    };
```

- **默认值：** development 模式为 `{ type: 'memory' }`（等价于 `true`），production 模式和 none 模式为 `false`

## 与 Incremental 的关系

Cache 和 [`incremental`](https://rspack.rs/zh/config/incremental.md) 相互正交。Cache 控制细粒度 Cache entry 的读取和存储；Incremental 控制开发期重建是否恢复上一轮 pass 的 Artifact，并根据已知 mutations 更新受影响的工作。

- `cache: false` 不会关闭 Incremental。
- `incremental: false` 不会关闭 Cache。
- FileSystem Cache 可以加速后续的一次性 build，但这属于 Cache 命中，而不是增量构建。

如果需要同时关闭两种复用机制，应显式设置两个选项：

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

## 内存缓存

将 `cache` 设置为 `true` 或 `{ type: 'memory' }` 可以启用内存缓存。内存缓存只保存在当前 compiler 进程中，主要用于 rebuild、watch 模式和 HMR。

内存缓存不会将缓存数据写入磁盘，因此进程结束后缓存会被清空，也无法加速后续重新启动的全新构建。它更适合开发阶段的长时间运行场景，例如同一个 compiler 实例持续处理多次重建。

```js title="rspack.config.mjs"
export default {
  cache: true,
};
```

或：

```js title="rspack.config.mjs"
export default {
  cache: {
    type: 'memory',
  },
};
```

## 持久化缓存

将 `cache` 设置为 `{ type: 'persistent' }` 可以启用基于文件系统的持久化缓存。持久化缓存会将缓存数据写入磁盘，以便后续构建进程复用。

```js title="rspack.config.mjs"
export default {
  cache: {
    type: 'persistent',
  },
};
```

### name

- **类型：** `string`
- **默认值：** 设置 `config.name` 时为 `<config.name>-<mode>`，否则为 `<mode>`

`cache.name` 用于命名持久化缓存。不同的名称会创建可同时存在的缓存。在 multi compiler 模式下，第一个 compiler 保持默认名称，后续 compiler 追加从零开始的 index，例如 `-1`、`-2`。

```js title="rspack.config.mjs"
export default {
  cache: {
    type: 'persistent',
    name: 'client-development',
  },
};
```

### buildDependencies

- **类型：** `string[]`
- **默认值：** `[]`

`cache.buildDependencies` 是构建依赖的文件或目录路径数组。Rspack 会追踪这些路径，并在任意被追踪的构建依赖发生变化时使持久化缓存失效。

```js title="rspack.config.mjs"
import { join } from 'node:path';

export default {
  cache: {
    type: 'persistent',
    buildDependencies: [
      import.meta.filename,
      join(import.meta.dirname, './tsconfig.json'),
    ],
  },
};
```

:::tip
与 webpack 不同，Rspack 默认不预设任何构建依赖。建议将未被 Rspack CLI 加载的项目配置文件添加到 `cache.buildDependencies`，以确保这些文件变化时缓存能及时失效。

注意：使用 Rspack CLI 时，配置文件会自动被添加到 `cache.buildDependencies` 中。

解析构建依赖时，Rspack 会递归遍历目录，并通过 AST 解析 JS/TS 文件以追踪传递依赖。对于解析到 `node_modules` 下的依赖，Rspack 会停止递归解析，并在可用时追踪对应包的 `package.json`。
:::

### version

- **类型：** `string`
- **默认值:** `""`

`cache.version` 用于标识持久化缓存数据的格式。当它与已存储的版本不一致时，Rspack 不会复用现有缓存，并会在构建完成后覆盖其内容。当配置发生不兼容变更时，应更新该值。

```js title="rspack.config.mjs"
export default {
  cache: {
    type: 'persistent',
    version: 'v1',
  },
};
```

:::warning
不要在不同配置之间共享同一份缓存（相同的 `cache.version` 和 `cache.storage.location`），这样可能导致错误的缓存命中。
:::

:::tip 持久化缓存失效

Rspack 会基于 `compilerPath` 的哈希拆分缓存子目录，每个 `compilerPath` 只保留一份缓存。[version](#version) 变化时，Rspack 会使该 compiler 的现有缓存失效并覆盖其内容，不会保留多个版本。

:::

### maxVersions


Stability: Deprecated

- **类型：** `number`
- **默认值：** 未设置

`cache.maxVersions` 仅为向后兼容而保留，但不会产生任何作用。Rspack 对每个 `compilerPath` 只保留一份持久化缓存。显式配置此选项时，Rspack 会输出弃用警告。

### maxMemoryGenerations

- **类型：** `number`（非负整数）或 `Infinity`
- **默认值：** development 模式为 `5`，production 和 none 模式为 `Infinity`

持久化缓存中未使用的条目在额外内存缓存中保留的代数。设置为 `0`
可禁用内存缓存，此后每次需要条目时都会从磁盘读取；设置为 `Infinity`
则会在 compiler 的整个生命周期内将条目保留在内存中。

```js title="rspack.config.mjs"
export default {
  cache: {
    type: 'persistent',
    maxMemoryGenerations: 0,
  },
};
```

### maxAge

- **类型：** `number`（正整数，单位为秒）或 `Infinity`
- **默认值：** `7 * 24 * 60 * 60`（7 天）

一份 compiler 缓存在未被访问后允许保留的最长时间，单位为秒。清理时，Rspack 会删除超过 `maxAge` 时间未被访问的 compiler 缓存目录。设置为 `Infinity` 可禁用基于时间的清理。

```js title="rspack.config.mjs"
export default {
  cache: {
    type: 'persistent',
    maxAge: 7 * 24 * 60 * 60,
  },
};
```

### portable

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

启用可移植缓存模式。启用后，生成的缓存内容可以在同一项目的不同平台和路径之间共享使用。

可移植缓存构建在持久化缓存之上，通过在序列化和反序列化过程中转换平台特定的数据（例如，将绝对路径转换为相对路径），使缓存具有平台无关性。

**示例：**

```js title="rspack.config.mjs"
export default {
  cache: {
    type: 'persistent',
    portable: true,
  },
};
```

:::tip 使用场景

典型的使用场景是在 CI 环境中，Windows、Linux 和 macOS 可以使用同一份缓存进行加速，而不需要生成三份独立的缓存副本。

:::

:::warning 限制

项目目录之外的文件（`config.context` 之外）会被转换为相对路径。如果这些文件在新环境中不存在，将会触发相关模块的重新构建。

:::

### readonly

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

启用只读缓存模式。启用后，缓存将仅从磁盘读取而不会被写入，这在 CI 环境中非常有用，可以使用预热的缓存而不修改它。

**示例：**

仅在 CI 启用：

```js title="rspack.config.mjs"
export default {
  cache: {
    type: 'persistent',
    // 请确保你的 CI 环境设置了 `process.env.CI`（或类似的环境变量）
    readonly: Boolean(process.env.CI),
  },
};
```

### snapshot

- **类型：** `object`
- **默认值：** `{ immutablePaths: [], managedPaths: [/[\\/]node_modules[\\/][^.]/], unmanagedPaths: [] }`

配置持久化缓存的快照策略，用于判断自上次构建以来哪些依赖发生了变化。

```js title="rspack.config.mjs"
export default {
  cache: {
    type: 'persistent',
    snapshot: {
      managedPaths: [/[\\/]node_modules[\\/]/],
    },
  },
};
```

#### snapshot.immutablePaths

- **类型：** `(RegExp | string)[]`
- **默认值：** `[]`

不可变路径数组。从持久化缓存恢复时，Rspack 会将匹配的路径视为未变化，并且不会重新检查其内容。适用于写入后保证不再变化的内容寻址路径。

```js title="rspack.config.mjs"
export default {
  cache: {
    type: 'persistent',
    snapshot: {
      immutablePaths: [/[\\/]\.yarn[\\/]cache[\\/]/],
    },
  },
};
```

#### snapshot.managedPaths

- **类型：** `(RegExp | string)[]`
- **默认值：** `[/[\\/]node_modules[\\/][^.]/]`

包管理器管理的路径数组。从持久化缓存恢复时，Rspack 会通过对应 `package.json` 中的 `version` 字段判断包是否发生变化，而不是对文件内容进行哈希。这可以加速对仅通过包管理器更新的依赖包的缓存校验。

```js title="rspack.config.mjs"
export default {
  cache: {
    type: 'persistent',
    snapshot: {
      managedPaths: [/[\\/]node_modules[\\/]/],
    },
  },
};
```

#### snapshot.unmanagedPaths

- **类型：** `(RegExp | string)[]`
- **默认值：** `[]`

指定 [`cache.snapshot.managedPaths`](#snapshotmanagedpaths) 中不应被视为包管理器管理的路径。这些路径下的文件会回退到基于内容哈希的缓存校验。

```js title="rspack.config.mjs"
export default {
  cache: {
    type: 'persistent',
    snapshot: {
      unmanagedPaths: [/[\\/]node_modules[\\/]my-linked-package[\\/]/],
    },
  },
};
```

### storage

- **类型：** `{ type: 'filesystem'; directory?: string; location?: string }`

配置缓存存储。目前仅支持文件系统存储。

```js title="rspack.config.mjs"
export default {
  cache: {
    type: 'persistent',
    storage: {
      type: 'filesystem',
    },
  },
};
```

#### storage.type

- **类型：** `'filesystem'`
- **默认值：** `'filesystem'`

通过 `type` 设置缓存存储类型。目前仅支持文件系统存储。

#### storage.directory

- **类型：** `string`
- **默认值：** `node_modules/.cache/rspack`

`cache.storage.directory` 是持久化缓存的基础目录，语义与 webpack 的 `cache.cacheDirectory` 一致。相对路径会基于 [`config.context`](https://rspack.rs/zh/config/context.md) 解析。

```js title="rspack.config.mjs"
export default {
  cache: {
    type: 'persistent',
    storage: {
      type: 'filesystem',
      directory: '.rspack-cache',
    },
  },
};
```

#### storage.location


[Added in v2.1.8](https://github.com/web-infra-dev/rspack/releases/tag/v2.1.8)

- **类型：** `string`
- **默认值：** `<storage.directory>/<cache.name>`

`cache.storage.location` 是 Rspack 实际读写缓存数据的完整路径，语义与 webpack 的 `cache.cacheLocation` 一致。未设置时，Rspack 会根据 `cache.storage.directory` 和 `cache.name` 推导该路径。相对路径会基于 [`config.context`](https://rspack.rs/zh/config/context.md) 解析。

```js title="rspack.config.mjs"
export default {
  context: '/project',
  cache: {
    type: 'persistent',
    name: 'client',
    storage: {
      type: 'filesystem',
      directory: '.rspack-cache',
    },
  },
};

// cache.storage.location 的默认值为 '/project/.rspack-cache/client'。
```

如需覆盖推导出的路径，可以显式设置 `storage.location`：

```js title="rspack.config.mjs"
export default {
  cache: {
    type: 'persistent',
    storage: {
      type: 'filesystem',
      location: '.custom-cache/client',
    },
  },
};
```

### 查看持久化缓存日志

持久化缓存相关日志会通过 `rspack.persistentCache` logger 输出。可以通过 `stats.loggingDebug` 开启这个 logger，在构建 stats 中查看这些日志：

```js title="rspack.config.mjs"
export default {
  cache: {
    type: 'persistent',
  },
  stats: {
    logging: false,
    loggingDebug: /^rspack\.persistentCache$/,
  },
};
```

日志会包含持久化缓存的关键信息，例如持久化缓存是否启用、构建依赖是否有效、缓存恢复是否成功，以及持久化缓存失效的原因。日志还会包含各缓存阶段的读写耗时（例如构建依赖校验、快照恢复、`occasion` 恢复、暂存以及刷盘）。

如果也想同时打印其他 logger 的日志，可以开启 `stats.logging`：

```js title="rspack.config.mjs"
export default {
  cache: {
    type: 'persistent',
  },
  stats: {
    logging: 'info',
    loggingDebug: /^rspack\.persistentCache$/,
  },
};
```

## 禁用缓存

将 `cache` 设置为 `false` 可以同时禁用内存缓存和持久化缓存，但不会关闭 [`incremental`](https://rspack.rs/zh/config/incremental.md)。如果工作流要求完整重建且不恢复 Artifact，需要另外设置 `incremental: false`。

通常不建议禁用缓存，因为未被 Incremental 跳过的计算将无法再复用细粒度 Cache entry。

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

## 从 webpack 迁移

请参考 [迁移 webpack - 缓存配置](https://rspack.rs/zh/guide/migration/webpack.md#cache-configuration)，了解如何将 webpack 缓存配置迁移到 Rspack。