#Compiler

Compiler 是 Rspack 内部的核心对象，当你调用 Rspack 的 JavaScript API 或 CLI 时，都会创建一个 Compiler 实例。

它提供了 run 和 watch 等方法来启动构建，同时暴露了丰富的 Compiler 钩子，使 Rspack 插件能够干预构建的各个阶段。

#Compiler 对象方法

#run

启动一次编译流程，编译流程完成或因错误中止时触发回调。

function run(
  callback: (
    error: Error, // 仅包含构建器相关错误，如配置错误等，不包含编译错误
    stats: Stats, // 编译过程中产生的信息
  ) => void,
  options?: {
    modifiedFiles?: ReadonlySet<string>; // 本次编译包含的被修改的文件
    removedFiles?: ReadonlySet<string>; // 本次编译包含的被删除的文件
  },
): void;

compiler.run((err, stats) => {
  // 处理构建器错误
  handleCompilerError(err);
  // 处理编译错误
  handleModuleErrors(stats.toJson().errors);
  // 处理构建结果
  handleBuildResult(stats);
  // 结束本次编译
  compiler.close((closeErr) => {
    // 重新启动一次编译
    compiler.run((err, stats) => {});
  });
});

#watch

启动持续监听，在文件变化后自动启动一次编译流程，每次编译流程完成或因错误中止时触发回调。

function watch(
  watchOptions: WatchOptions, // 启动监听的配置
  handler: (error: Error, stats: Stats) => void, // 每次编译流程完成或因错误中止时触发回调
): Watching; // 监听控制实例

const watching = compiler.watch(
  {
    aggregateTimeout: 300,
    poll: undefined,
  },
  (err, stats) => {
    // 处理构建结果
    handleBuildResult(stats);
  },
);

Watching 对象提供如下方法：

• watch:
  • 类型： (files: Iterable<string>, dirs: Iterable<string>, missing: Iterable<string>): void
  • 用途： 添加需要被监听的文件和目录
• invalidate:
  • 类型： (callback: () => void): void
  • 用途： 立即结束本轮监听，并以当前记录的文件变更启动一次编译流程，不会停止整个监听器。
• suspend:
  • 类型： (): void
  • 用途： 进入仅监听状态，不会启动新的编译流程
• resume:
  • 类型： (): void
  • 用途： 退出仅监听状态，并以当前记录的文件变更启动一次编译流程
• close:
  • 类型： (callback: () => void): void
  • 用途： 停止整个监听器

#close

关闭当前构建器，在此期间处理低优先级任务，如缓存等。

function close(
  callback: (err: Error) => void, // 关闭完成后回调
): void;

#getInfrastructureLogger

创建一个不与 Compilation 关联的全局日志对象，用于打印全局信息。

function getInfrastructureLogger(name: string): Logger;

#getCache

创建一个缓存对象，以在构建流程中共享数据。

function getCache(name: string): CacheFacade;

#purgeInputFileSystem

停止对文件系统的读取循环，它内部包含定时器，可能会导致 compiler.close 后进程依然无法退出。

function purgeInputFileSystem(): void;

#createChildCompiler

创建并返回一个子 Compiler，可以为其指定输出选项和额外插件。钩子和插件的继承规则见 compilation.createChildCompiler。

function createChildCompiler(
  compilation: Compilation,
  compilerName: string,
  compilerIndex: number,
  outputOptions: OutputOptions,
  plugins?: (RspackPluginInstance | Falsy)[],
): Compiler;

#runAsChild

启动子 Compiler 的构建流程，会进行一次完整的构建流程并生成产物。

function runAsChild(
  callback(
    err: Error, // 子 Compiler 执行的构建器错误
    entries: Chunk[], // 子 Compiler 执行产生的 Chunk 信息
    compilation: Compilation, // 子 Compiler 所创建的 Compilation 对象
  ): void;
): void;

#isChild

当前是否为子 Compiler。

function isChild(): boolean;

#Compiler 对象属性

#hooks

详见 Compiler 钩子

#rspack

• 类型： typeof rspack

获取当前的 @rspack/core 的导出，以此来获取关联的内部对象。当你无法直接引用 @rspack/core，或者存在多个 Rspack 实例时很有用。

一个常见的例子是在 Rspack 插件中获取 sources 对象：

const { RawSource } = compiler.rspack.sources;
const source = new RawSource('console.log("Hello, world!");');

#webpack

• 类型： typeof rspack

等同于 compiler.rspack，该属性用于兼容 webpack 插件。

如果你开发的 Rspack 插件需要兼容 webpack，可以使用该属性代替 compiler.rspack。

console.log(compiler.webpack === compiler.rspack); // true

#name

• 类型： string

获取名称：

• 对于根 Compiler 等同于 name
• 对于子 Compiler 时为 createChildCompiler 传入的值
• 对于 MultiCompiler 且为 KV 形式时为 Key 的值

#context

当前的项目根目录：

• 通过 new Compiler 时为传入的值
• 通过 rspack({}) 等创建时同于 context 配置

#root

• 类型： Compiler

获取根 Compiler 实例。

#options

• 类型： RspackOptionsNormalized

获取根 Compiler 所使用的完整构建配置。

#target

• 类型：

type CompilerTarget = {
  // ECMAScript 版本
  esVersion?: number | null;
  // 包含版本号的平台名称
  targets?: Record<string, string> | null;
};

从 target 配置中推断出。这对需要访问目标环境信息的插件和 loader 作者非常有用。

• targets: 包含平台名称及其版本的对象（例如：{ 'chrome': '87', 'firefox': '78', 'node': '18' }）。
• esVersion: ECMAScript 版本号（例如：5, 2015, 2022）。

例如，在插件中访问 compiler.target：

class ExamplePlugin {
  apply(compiler) {
    compiler.hooks.initialize.tap('ExamplePlugin', () => {
      const { targets, esVersion } = compiler.target ?? {};
      console.log(targets, esVersion);
    });
  }
}

或是在自定义 loader 中访问 compiler.target：

export default function myLoader(source) {
  const options = this.getOptions();
  const compilerTarget = this._compiler.target ?? {};
  // 使用用户指定的 targets，或者回退到 Rspack 推断出的 targets
  const targets = options.targets ?? compilerTarget.targets;
  // 需要时回退到 Rspack 推断出的 ECMAScript 版本
  const ecmaVersion = options.ecmaVersion ?? compilerTarget.esVersion;
  // 使用 targets 进行转换...
  return transform(source, { targets, ecmaVersion });
}

#watchMode

• 类型： boolean

是否通过 watch 启动。

#watching

• 类型： Watching

获取 watch 启动下的监听控制对象，详见 watch 方法

#running

• 类型： boolean

当前是否正在执行构建流程。

#inputFileSystem

• 类型： InputFileSystem

获取用于从文件系统读取的代理对象，其内部有缓存等优化，以降低对同一文件的重复读取。

#outputFileSystem

• 类型： OutputFileSystem

获取用于输出到文件系统的代理对象，默认使用 fs。

#watchFileSystem

• 类型： WatchFileSystem

获取用于持续监听文件/目录变化的代理对象，提供一个 watch 方法来启动监听，并在回调中传入变更和移除的项目。

#MultiCompiler

MultiCompiler 可以让 Rspack 同时执行多份配置。如果传给 Rspack 的 JavaScript API 的配置为多个配置对象构成的数组，Rspack 会创建多个 compiler 实例，并且在所有 compiler 执行完毕后调用回调方法。

import { rspack } from '@rspack/core';

rspack(
  [
    { entry: './index1.js', output: { filename: 'bundle1.js' } },
    { entry: './index2.js', output: { filename: 'bundle2.js' } },
  ],
  (err, stats) => {
    process.stdout.write(stats.toString() + '\n');
  },
);

也可以通过 new MultiCompiler 创建：

const compiler1 = new Compiler({/* */});
const compiler2 = new Compiler({/* */});

new MultiCompiler([compiler1, compiler2]);

new MultiCompiler([compiler1, compiler2], {
  parallelism: 1, // 控制最大并行数量
});

new MultiCompiler({
  name1: compiler1,
  name2: compiler2,
});

MultiCompiler 也提供了部分 Compiler 的方法和属性。

#MultiCompiler 方法

#setDependencies

指定 compiler 之间的依赖关系，以 compiler.name作为标识，以此保证 compiler 执行顺序。

setDependencies(compiler: Compiler, dependencies: string[]): void;

#validateDependencies

检测 compiler 之间的依赖关系是否合法，若成环或缺失会触发回调。

validateDependencies(
  callback: (err: Error) => void; // 错误时回调，若多个错误会回调多次
): boolean

#run

根据依赖关系执行各个 compiler 的 run 方法，启动编译流程。

run(
  callback: (err: Error, stats: MultiStats) => void,
  options?: {
    modifiedFiles?: ReadonlySet<string>; // 本次编译包含的被修改的文件
    removedFiles?: ReadonlySet<string>; // 本次编译包含的被删除的文件
  },
): void;

#watch

根据依赖关系执行各个 compiler 的 watch 方法，启动持续监听，在文件变化后自动启动一次编译流程。

function watch(
  watchOptions: WatchOptions | WatchOptions[],
  handler: (err: Error, stats: MultiStats) => void,
): MultiWatching;

#close

执行各个 compiler 的 close 方法，关闭构建器，并在此期间处理低优先级任务，如缓存等。

close(callback: (err: Error) => void): void;

#purgeInputFileSystem

执行各个 compiler 的 purgeInputFileSystem，停止对文件系统的读取循环。

purgeInputFileSystem(): void;

#getInfrastructureLogger

创建一个不与 Compilation 关联的全局日志对象，用于打印全局信息。

getInfrastructureLogger(name: string): Logger;

等同于 compilers[0].getInfrastructureLogger()

#MultiCompiler 属性

#compilers

• 类型： Compiler[]

获取包含的所有 Compiler 实例。

#options

• 类型： RspackOptionsNormalized[]

获取各个 Compiler 所使用的完整构建配置。

#inputFileSystem

• 类型： InputFileSystem

为各个 Compiler 设置用于从文件系统读取的代理对象。

#outputFileSystem

• 类型： OutputFileSystem

为各个 Compiler 设置用于输出到文件系统的代理对象。

#watchFileSystem

• 类型： WatchFileSystem

为各个 Compiler 设置用于持续监听文件/目录变化的代理对象。

#running

• 类型： boolean

当前是否正在执行构建流程。