#Cache

cache 选项用于控制 Rspack 的缓存策略，让 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;
        maxAge?: number;
        maxGenerations?: number;
      };
    };

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

#内存缓存

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

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

export default {
  cache: true,
};

或：

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

#持久化缓存

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

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

#buildDependencies

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

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

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')],
  },
};

#version

• 类型： string
• 默认值: ""

cache.version 是写入持久化缓存 key 的额外版本字符串。可以通过修改它来手动隔离或使持久化缓存失效。

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

#portable

• 类型： boolean
• 默认值： false

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

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

示例：

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

#readonly

• 类型： boolean
• 默认值： false

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

示例：

仅在 CI 启用：

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

#snapshot

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

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

export default {
  cache: {
    type: 'persistent',
    snapshot: {
      managedPaths: [/[\\/]node_modules[\\/]/],
    },
  },
};

#snapshot.immutablePaths

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

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

export default {
  cache: {
    type: 'persistent',
    snapshot: {
      immutablePaths: [/[\\/]\.yarn[\\/]cache[\\/]/],
    },
  },
};

#snapshot.managedPaths

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

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

export default {
  cache: {
    type: 'persistent',
    snapshot: {
      managedPaths: [/[\\/]node_modules[\\/]/],
    },
  },
};

#snapshot.unmanagedPaths

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

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

export default {
  cache: {
    type: 'persistent',
    snapshot: {
      unmanagedPaths: [/[\\/]node_modules[\\/]my-linked-package[\\/]/],
    },
  },
};

#storage

• 类型： { type: 'filesystem'; directory?: string; maxAge?: number; maxGenerations?: number }

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

export default {
  cache: {
    type: 'persistent',
    storage: {
      type: 'filesystem',
      maxAge: 7 * 24 * 60 * 60,
      maxGenerations: 10,
    },
  },
};

#storage.type

• 类型： 'filesystem'
• 默认值： 'filesystem'

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

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

#storage.directory

• 类型： string
• 默认值： node_modules/.cache/rspack/<mode> 或 node_modules/.cache/rspack/<name>-<mode>

通过 directory 设置缓存目录。默认目录会基于 config.context、config.name、config.mode 和 multi compiler 的 index 生成。在 multi compiler 模式下，后续 compiler 会追加 -<index> 以避免共享同一个目录。

export default {
  cache: {
    type: 'persistent',
    storage: {
      directory: '.rspack-cache',
    },
  },
};

#storage.maxAge

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

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

export default {
  cache: {
    type: 'persistent',
    storage: {
      type: 'filesystem',
      maxAge: 7 * 24 * 60 * 60,
    },
  },
};

#storage.maxGenerations

• 类型： number（正整数）或 Infinity
• 默认值： 3

控制当前缓存目录最多保留多少个缓存版本。超过限制时，Rspack 会优先删除较旧且未处于当前使用状态的缓存版本。设置为 Infinity 可禁用基于数量的清理。

export default {
  cache: {
    type: 'persistent',
    storage: {
      type: 'filesystem',
      maxGenerations: 10,
    },
  },
};

#查看持久化缓存日志

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

export default {
  cache: {
    type: 'persistent',
  },
  stats: {
    logging: false,
    loggingDebug: /^rspack\.persistentCache$/,
  },
};

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

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

export default {
  cache: {
    type: 'persistent',
  },
  stats: {
    logging: 'info',
    loggingDebug: /^rspack\.persistentCache$/,
  },
};

#禁用缓存

将 cache 设置为 false 可以同时禁用内存缓存和持久化缓存。通常不建议禁用缓存，因为这会导致开发阶段的重构建显著变慢。

export default {
  cache: false,
};

#从 webpack 迁移

请参考 迁移 webpack - 缓存配置，了解如何将 webpack 缓存配置迁移到 Rspack。