Experiments#

该选项允许用户开启和尝试一些实验性的功能。

• 类型： object

experiments.asyncWebAssembly#

• 类型： boolean
• 默认值： false

支持基于新规范的 WebAssembly，这使 WebAssembly 模块成为异步模块。

module.exports = {
  experiments: {
    asyncWebAssembly: true,
  },
};

当设置 experiments.futureDefaults 为 true 时，默认启用此功能。

experiments.outputModule#

• 类型： boolean
• 默认值： false

开启之后，将尽可能输出符合 ECMAScript 语法的代码。例如，使用 import() 加载 chunk，使用 ESM exports 等等。

module.exports = {
  experiments: {
    outputModule: true,
  },
};

experiments.css#

• 类型： boolean
• 默认值： false

启用原生 CSS 支持和 CSS 相关的 parser 和 generator options：

• module.parser["css/auto"]
• module.parser.css
• module.parser["css/module"]
• module.generator["css/auto"]
• module.generator.css
• module.generator["css/module"]

基本示例：

module.exports = {
  experiments: {
    css: true,
  },
};

experiments.futureDefaults#

使用下一个主版本 Rspack 的默认值，并在任何有问题的地方显示警告。

module.exports = {
  experiments: {
    futureDefaults: true,
  },
};

experiments.topLevelAwait#

开启打包 Top-level await 的支持，Top-level await 仅能在 ModuleType 为 javascript/esm 的模块中使用。

默认开启，可通过该配置关闭：

module.exports = {
  experiments: {
    topLevelAwait: false,
  },
};

experiments.lazyCompilation#

• 类型： boolean | LazyCompilationOptions
• 默认值： false

type LazyCompilationOptions =
  | boolean
  | {
      backend?: {
        /**
         * A custom client.
         */
        client?: string;
        /**
         * Specify where to listen to from the server.
         */
        listen?: number | ListenOptions;
        /**
         * Specify the protocol the client should use to connect to the server.
         */
        protocol?: 'http' | 'https';
      };
      /**
       * 为 entries 启用 lazy compilation
       */
      entries?: boolean;
      /**
       * 为 dynamic imports 启用 lazy compilation
       */
      imports?: boolean;
      /**
       * 指定哪些导入的模块应该被延迟编译
       */
      test?: RegExp | ((m: Module) => boolean);
    };

开启懒编译，这对提高多入口应用（MPA）或大型单页面应用（SPA）的 dev 启动性能会非常有帮助。例如你有二十个入口，只有访问到的入口才会进行构建，或者如果项目中存在非常多的 import()，每一个 import() 所指向的模块都只有在被真正访问到时，才进行构建。

如果设置为 true，则默认会对入口模块以及 import() 指向的模块进行懒编译。你可以通过配置对象形式，来决定是否只对入口或只对 import() 生效。entries 决定是否对入口生效，import() 决定是否对 import() 生效。

const isDev = process.env.NODE_ENV === 'development';

module.exports = {
  experiments: {
    // 仅在 dev 模式下开启
    lazyCompilation: isDev,
  },
};

除此以外你还可以配置 test 来更细粒度控制对哪些模块进行懒编译。test 可以是一个正则表达式，只对该正则匹配到的模块进行懒编译，test 也可以是一个函数，函数的输入是 Module 类型，返回 boolean 类型，表示是否命中懒编译逻辑。

lazyCompilation.backend.listen#

• 类型： number | ListenOptions

type ListenOptions = {
  port?: number | undefined;
  host?: string | undefined;
  backlog?: number | undefined;
  path?: string | undefined;
  exclusive?: boolean | undefined;
  readableAll?: boolean | undefined;
  writableAll?: boolean | undefined;
  /**
   * @default false
   */
  ipv6Only?: boolean | undefined;
};

排除 HMR client#

如果你未使用 Rspack 的 dev server，而是使用自己的 server 作为开发服务器，一般会在 entry 配置中加入另外的 client 代码来开启 HMR 等能力，那么最好通过配置 test 来将该 client 模块从懒编译模块中排除出去。

如果不排除掉，并且开启 entry 的懒编译，该 client 在第一次访问页面时不会被编译，因此需要一次额外的刷新才能让其真正生效。

const rspack = require('@rspack/core');

const options = {
  experiments: {
    lazyCompilation: {
      test(module) {
        const isMyClient = module.nameForCondition().endsWith('dev-client.js');
        // 让 dev-client.js 不被懒编译
        return !isMyClient;
      },
    },
  },
};
const compiler = rspack(options);

new compiler.webpack.EntryPlugin(compiler.context, 'dev-client.js', {
  // name: undefined 代表这是全局 entry，会插入到每一个 entry 前
  name: undefined,
}).apply(compiler);

experiments.layers#

• 类型： boolean
• 默认值： false

控制是否启用 layer 功能，layer 可以为模块图中以一个模块作为起点的子图中的所有模块添加标识符前缀，用来与其他不同 layer 的模块进行区分，比如：

index.js 模块的 layer 为默认的 null，其 identifier 为 ./index.js，我们为其添加 layer = 'client'，其 identifier 会变成 (client)/./index.js，这时这两个不同 layer 的 index.js 会被区分为不同的模块，因为其唯一标识 identifier 不一样，最终产物中也会存在这两个模块的产物。

模块默认的 layer 为 null，模块默认会继承其父模块的 layer，你可以通过 entryOptions.layer 为一个入口模块添加 layer，也可以通过 module.rule[].layer 为匹配到的模块添加 layer，同时可以通过 module.rule[].issuerLayer 根据父模块的 layer 进行匹配。

module.exports = {
  experiments: {
    layers: true,
  },
};

experiments.incremental#

• 类型： boolean | Incremental
• 默认值：production 模式 为false, development 模式 为{ make: true, emitAssets: true }

type Incremental = {
  make?: boolean;
  inferAsyncModules?: boolean;
  providedExports?: boolean;
  dependenciesDiagnostics?: boolean;
  buildChunkGraph?: boolean;
  moduleIds?: boolean;
  chunkIds?: boolean;
  modulesHashes?: boolean;
  modulesCodegen?: boolean;
  modulesRuntimeRequirements?: boolean;
  chunksRuntimeRequirements?: boolean;
  chunksHashes?: boolean;
  chunksRender?: boolean;
  emitAssets?: boolean;
};

是否增量地进行重构建，加快重构建或 HMR 的速度，建议仅在开发时启用：

const isDev = process.env.NODE_ENV;
module.exports = {
  mode: isDev ? 'development' : 'production',
  experiments: {
    incremental: isDev,
  },
};

true 表示对全部阶段启用增量，false 表示对全部阶段关闭增量，也可以仅对指定的部分阶段开启增量：

module.exports = {
  experiments: {
    // 对全部阶段启用增量
    incremental: true,
    // 对全部阶段关闭增量
    incremental: false,
    // 仅对指定的部分阶段开启增量
    incremental: {
      make: true,
      emitAssets: true,
    },
  },
};

目前 Rspack 默认开启 make 和 emitAssets 阶段的增量，这也是之前 Rspack v1.0 的默认行为。随着该特性的进一步稳定，我们会默认开启更多阶段的增量，直到完全启用。

experiments.rspackFuture#

• 类型： object
• 默认值： 参考下方各项配置

用于控制是否开启 Rspack 未来的默认行为，详情请参考这里。

rspackFuture.bundlerInfo#

• 类型：

  type BundlerInfo = {
    version?: string,
    bundler?: string,
    force?: ('version' | 'uniqueId')[] ｜ boolean;
  };

用于在生成产物中注入当前使用的 Rspack 信息。其中：

• version：用于指定 Rspack 版本，默认读取 @rspack/core/package.json 中的 version 字段。
• bundler：用于指定打包工具名称，默认为 rspack
• force：是否强制注入 Rspack 信息，会以运行时模块的形式加入到产物中，默认为 true 即强制注入，可通过数组选择强制注入的项目。

关闭默认注入#

可通过将 force 设定为 false 来关闭默认注入，此时仅在检测到代码中使用了 __rspack_version__ 和 __rspack_unique_id__ 时才会注入：

• __rspack_version__：注入版本信息
• __rspack_unique_id__：注入打包工具唯一ID

module.exports = {
  experiments: {
    rspackFuture: {
      bundlerInfo: { force: false },
    },
  },
};

experiments.cache#

• 类型： ExperimentCacheOptions

• 默认值： production 模式 为 false, development 模式 为 true

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

控制实验性的缓存行为，此配置依赖全局开启缓存，需配置 全局cache 为 true 才有效。

禁用缓存#

可以配置 experiment.cache 为 false 来禁用缓存，此时与配置 全局cache 为 false 没有差别。

module.exports = {
  experiment: {
    cache: false,
  },
};

内存缓存#

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

module.exports = {
  experiment: {
    cache: true,
  },
};

持久化缓存#

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

module.exports = {
  experiment: {
    cache: {
      type: 'persistent',
    },
  },
};

cache.buildDependencies#

• 类型： string[]

• 默认值： []

cache.buildDependencies 是一个包含构建依赖的文件数组，Rspack 将使用其中每个文件的哈希值来使持久化缓存无效。

module.exports = {
  experiment: {
    cache: {
      type: 'persistent',
      buildDependencies: [__filename, path.join(__dirname, './tsconfig.json')],
    },
  },
};

cache.version#

• 类型： string

• 默认值： ""

缓存数据的版本，不同版本缓存相互隔离。

cache.snapshot#

配置快照策略，Snapshot 用于在热启动时判断哪些文件在停机时被修改。支持以下配置:

snapshot.immutablePaths#

• 类型： (RegExp | string)[]

• 默认值： []

不可变文件的路径数组，这些文件的变动在热启动时会被忽略。

snapshot.managedPaths#

• 类型： (RegExp | string)[]

• 默认值： [/\/node_modules\//]

由包管理器管理的路径数组，热启动时会通过 package.json 中的版本来判断是否修改。

snapshot.unmanagedPaths#

• 类型： (RegExp | string)[]

• 默认值： []

指定 snapshot.managedPaths 中不受包管理器管理的路径数组。

cache.storage#

• 类型： { type: 'filesystem', directory: string }

• 默认值： { type: 'filesystem', directory: 'node_modules/.cache/rspack' }

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

module.exports = {
  experiment: {
    cache: {
      type: 'persistent',
      storage: {
        type: 'filesystem',
        directory: 'node_modules/.cache/rspack',
      },
    },
  },
};