Cache

缓存：该选项可以开启或者关闭 Rspack 构建过程中对快照及中间产物的缓存，如果开启，在下次构建中可以使用它们来提升构建的速度。

类型：

type CacheOptions =
  | boolean
  | {
      type: 'memory';
    }
  | {
      type: 'persistent';
      buildDependencies?: string[];
      version?: string;
      portable?: boolean;
      readonly?: boolean;
      snapshot?: {
        immutablePaths?: Array<string | RegExp>;
        unmanagedPaths?: Array<string | RegExp>;
        managedPaths?: Array<string | RegExp>;
      };
      storage?: {
        type: 'filesystem';
        directory?: string;
      };
    };

默认值： development 模式为 true，production 模式和 none 模式为 false

禁用缓存

可以配置 cache 为 false 来禁用缓存。

rspack.config.mjs

export default {
  cache: false,
};

内存缓存

可以配置 cache 为 true 或 { type: "memory" } 来启用内存缓存。

rspack.config.mjs

export default {
  cache: true,
};

或

rspack.config.mjs

export default {
  cache: {
    type: 'memory',
  },
};

持久化缓存

可以配置 cache 为 { type: "persistent" } 来启用持久化缓存。

rspack.config.mjs

export default {
  cache: {
    type: 'persistent',
  },
};

cache.buildDependencies

类型： string[]
默认值： []

cache.buildDependencies 是一个包含构建依赖的文件数组，Rspack 会使用这些文件的哈希值来使持久化缓存失效。

Tip

与 webpack 不同，Rspack 默认不预设任何构建依赖。建议将项目配置文件添加到 cache.buildDependencies，以确保配置变更时缓存能及时失效。

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

在解析构建依赖文件时，Rspack 会通过 AST 递归解析 JS/TS 文件，追踪其传递依赖。对于 node_modules 下的包，Rspack 会停止递归解析，转而追踪该包的 package.json。

rspack.config.mjs

import { fileURLToPath } from 'node:url';
import { dirname, join } from 'node:path';

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

export default {
  cache: {
    type: 'persistent',
    buildDependencies: [__filename, join(__dirname, './tsconfig.json')],
  },
};

cache.version

类型： string
默认值: ""

缓存版本，不同版本的缓存彼此隔离。

Warning

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

持久化缓存失效

除了 buildDependencies 和 version 配置会影响持久化缓存失效外，以下字段变化时 Rspack 也会使持久化缓存失效。

cache.portable

类型： boolean
默认值： false

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

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

使用场景

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

示例：

rspack.config.mjs

export default {
  cache: {
    type: 'persistent',
    portable: true,
  },
};

限制

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

cache.readonly

类型： boolean
默认值： false

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

示例：

仅在 CI 启用：

rspack.config.mjs

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

cache.snapshot

类型： object
默认值： {}

配置快照策略。快照用于确定自上次构建以来哪些文件发生了变化。支持以下配置：

snapshot.immutablePaths

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

不可变文件的路径数组。热重启时，这些路径下的文件变更将被忽略，缓存会直接视为有效而无需重新检查文件内容。适用于保证写入后永不变更的内容寻址路径。

snapshot.managedPaths

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

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

snapshot.unmanagedPaths

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

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

cache.storage

类型： { type: 'filesystem'; directory?: string }
默认值： { type: 'filesystem', directory: 'node_modules/.cache/rspack' }

配置缓存存储。目前仅支持文件系统存储。可通过 directory 设置缓存目录。默认为 node_modules/.cache/rspack。

rspack.config.mjs

export default {
  cache: {
    type: 'persistent',
    storage: {
      type: 'filesystem',
      directory: 'node_modules/.cache/rspack',
    },
  },
};

Tip

Rspack 将基于 config.name、config.mode、buildDependencies 中的文件内容和 version 在 storage.directory 中生成缓存文件夹。

Rspack 会在启动时自动清理长时间（7 天）未访问的缓存文件夹。

从 webpack 配置迁移

Rspack 的缓存配置与 webpack 的缓存配置不同。你可以参考以下步骤迁移 webpack 的缓存配置。

根据缓存类型，设置 Rspack 缓存类型。对于持久化缓存继续下一步，对于其他类型的缓存到此结束。

rspack.config.mjs

export default {
- cache: {
-   type: 'filesystem',
- },
+ cache: {
+   type: 'persistent',
+ },
};

迁移 cache.buildDependencies

rspack.config.mjs

export default {
- cache: {
-   buildDependencies: {
-     config: [__filename, path.join(__dirname, "package.json")],
-     ts: [path.join(__dirname, "tsconfig.json")]
-   }
- },
+ cache: {
+   type: "persistent",
+   buildDependencies: [
+     __filename,
+     path.join(__dirname, "package.json"),
+     path.join(__dirname, "tsconfig.json")
+   ]
+ },
};

迁移 cache.version 和 cache.name

rspack.config.mjs

export default {
- cache: {
-   name: `${config.name}-${config.mode}-${otherFlags}`,
-   version: appVersion
- },
+ cache: {
+   type: "persistent",
+   version: `${config.name}-${config.mode}-${otherFlags}-${appVersion}`
+ },
};

迁移 snapshot

rspack.config.mjs

export default {
- snapshot: {
-   immutablePaths: [path.join(__dirname, "constant")],
-   managedPaths: [path.join(__dirname, "node_modules")],
-   unmanagedPaths: []
- },
+ cache: {
+   type: "persistent",
+   snapshot: {
+     immutablePaths: [path.join(__dirname, "constant")],
+     managedPaths: [path.join(__dirname, "node_modules")],
+     unmanagedPaths: []
+   }
+ },
};

迁移 cache.cacheDirectory

rspack.config.mjs

export default {
- cache: {
-   cacheDirectory: path.join(__dirname, "node_modules/.cache/test")
- },
+ cache: {
+   type: "persistent",
+   storage: {
+     type: "filesystem",
+     directory: path.join(__dirname, "node_modules/.cache/test")
+   }
+ },
};

示例迁移代码：

function transform(webpackConfig, rspackConfig) {
  if (webpackConfig.cache === undefined) {
    webpackConfig.cache = webpackConfig.mode === 'development';
  }
  // 1. 如果使用禁用缓存，只需设置 `cache` = false
  if (!webpackConfig.cache) {
    rspackConfig.cache = false;
    return;
  }
  // 2. 如果使用内存缓存，只需设置 `cache` = true
  if (webpackConfig.cache === true || webpackConfig.cache.type === 'memory') {
    rspackConfig.cache = true;
    return;
  }
  // 3. 使用持久化缓存，设置 `cache` = { type: "persistent" }
  rspackConfig.cache = { type: 'persistent' };
  // 4. 从 webpack 配置构建 `cache`
  rspackConfig.cache.buildDependencies = Object.values(
    webpackConfig.cache.buildDependencies || {},
  ).flat();
  rspackConfig.cache.version = [
    webpackConfig.cache.name,
    webpackConfig.cache.version,
  ].join();
  rspackConfig.cache.snapshot = {
    immutablePaths: webpackConfig.snapshot?.immutablePaths,
    managedPaths: webpackConfig.snapshot?.managedPaths,
    unmanagedPaths: webpackConfig.snapshot?.unmanagedPaths,
  };
  rspackConfig.cache.storage = {
    type: 'filesystem',
    directory: webpackConfig.cache?.cacheDirectory,
  };
}

#Cache

#禁用缓存

#内存缓存

#持久化缓存

#cache.buildDependencies

#cache.version

#cache.portable

#cache.readonly

#cache.snapshot

#snapshot.immutablePaths

#snapshot.managedPaths

#snapshot.unmanagedPaths

#cache.storage

#从 webpack 配置迁移

Cache

禁用缓存

内存缓存

持久化缓存

cache.buildDependencies

cache.version

cache.portable

cache.readonly

cache.snapshot

snapshot.immutablePaths

snapshot.managedPaths

snapshot.unmanagedPaths

cache.storage

从 webpack 配置迁移