#Compiler 钩子

Compiler hooks 允许 Rspack 插件在特定阶段介入构建流程。它们代表了从初始化到资源输出的各个生命周期阶段。

本文档列举了 Rspack 中可用的 Compiler 钩子、它们的触发时机、参数以及使用示例。

#Overview

#environment

在编译器准备环境时，初始化插件之后调用。

• 类型： SyncHook<[]>

#afterEnvironment

当编译器环境准备完成后，在 environment 钩子后直接调用。

• 类型： SyncHook<[]>

#entryOption

在 Rspack 选项中的 entry 被处理过之后调用。

• 类型： SyncBailHook<[string, EntryNormalized]>
• 参数：
  • string: 等同于 context 配置
  • EntryNormalized: 处理后的 entry 配置

#afterPlugins

在初始化内部插件完成之后调用。

• 类型： SyncHook<[Compiler]>
• 参数：
  • Compiler: 当前 Compiler 实例

#afterResolvers

resolver 设置完成之后触发。

• 类型： SyncHook<[Compiler]>
• 参数：
  • Compiler: 当前 Compiler 实例

#initialize

当编译器被初始化时调用。

• 类型： SyncHook<[]>

#beforeRun

在开始执行一次构建之前调用。

• 类型： AsyncSeriesHook<[Compiler]>
• 参数：
  • Compiler: 当前 Compiler 实例

• 示例： 同步操作

class ExamplePlugin {
  apply(compiler) {
    compiler.hooks.beforeRun.tap('ExamplePlugin', compiler => {
      console.log('Build is about to start...');
    });
  }
}

• 示例： 异步操作

class ExamplePlugin {
  apply(compiler) {
    compiler.hooks.beforeRun.tapPromise(
      'ExamplePlugin',
      (compiler) => {
        console.log('Build is about to start...');

        await someAsyncOperation();
      },
    );
  }
}

#run

在开始执行一次构建时调用。

• 类型： AsyncSeriesHook<[Compiler]>
• 参数：
  • Compiler: 当前 Compiler 实例

• 示例： 同步操作

class ExamplePlugin {
  apply(compiler) {
    compiler.hooks.beforeRun.tap('ExamplePlugin', compiler => {
      console.log('Build start...');
    });
  }
}

• 示例： 异步操作

class ExamplePlugin {
  apply(compiler) {
    compiler.hooks.beforeRun.tapPromise(
      'ExamplePlugin',
      (compiler) => {
        console.log('Build start...');

        await someAsyncOperation();
      },
    );
  }
}

#watchRun

在监听模式下，开始执行一次构建时调用。

你可以通过 compiler.modifiedFiles 和 compiler.removedFiles 获取变更的文件路径和删除的文件路径。

• 类型： AsyncSeriesHook<[Compiler]>
• 参数：
  • Compiler: 当前 Compiler 实例

• 示例： 同步操作

class ExamplePlugin {
  apply(compiler) {
    compiler.hooks.watchRun.tap('ExamplePlugin', compiler => {
      const { modifiedFiles, removedFiles } = compiler;
      if (modifiedFiles) {
        console.log('Changed files:', Array.from(modifiedFiles));
      }
      if (removedFiles) {
        console.log('Removed files:', Array.from(removedFiles));
      }
    });
  }
}

• 示例： 异步操作

class ExamplePlugin {
  apply(compiler) {
    compiler.hooks.watchRun.tapPromise('ExamplePlugin', compiler => {
      await someAsyncOperation();
    });
  }
}

#beforeCompile

在编译参数创建后执行插件。

• 类型： AsyncSeriesHook<[]>

#compile

在一个新的 compilation 对象 被创建之前调用。

• 类型： SyncHook<[]>

#thisCompilation

在创建 compilation 对象时调用，用于获取当前的 compilation 对象。

你可以通过 compilation 参数来访问 compilation 对象的属性，或是注册 compilation hooks。

• 类型： SyncHook<[Compilation]>
• 参数：
  • compilation: 创建的 compilation 对象

• 示例：

class ExamplePlugin {
  apply(compiler) {
    compiler.hooks.thisCompilation.tap('ExamplePlugin', compilation => {
      console.log('compilation created:', compilation);

      compilation.hooks.make.tap('ExamplePlugin', compilation => {
        console.log("compilation's make hook called:", compilation);
      });
    });
  }
}

#compilation

在 compilation 对象创建之后调用，用于获取当前的 compilation 对象。

你可以使用 compilation 参数来访问 compilation 对象的属性，或是注册 compilation hooks。

compilation 钩子的调用晚于 thisCompilation 钩子，并且 thisCompilation 钩子不会被复制到 child compiler 中，而 compilation 钩子会被复制到 child compiler 中。

• 类型： SyncHook<[Compilation]>
• 参数：
  • compilation: 创建的 compilation 对象

class ExamplePlugin {
  apply(compiler) {
    compiler.hooks.compilation.tap('ExamplePlugin', compilation => {
      console.log('compilation created:', compilation);

      compilation.hooks.make.tap('ExamplePlugin', compilation => {
        console.log("compilation's make hook called:", compilation);
      });
    });
  }
}

#make

在 make 阶段开始前调用，在 make 阶段会以 entry 为起点构建模块依赖图，并使用 loader 处理各个模块。

• 类型： AsyncParallelHook<[Compilation]>
• 参数：
  • Compilation: 当前 Compilation 对象

#finishMake

在 make 阶段结束后调用。在 make 阶段，Rspack 会以 entry 为起点构建模块依赖图，并使用 loader 处理各个模块，当这个过程完成时会触发此钩子。

• 类型： AsyncSeriesHook<[Compilation]>
• 参数：
  • Compilation: 当前 Compilation 对象

#afterCompile

在 make 阶段结束后 seal 阶段开始前调用，在 seal 阶段会从模块图优化并创建 chunk 图，以生成产物信息。

• 类型： AsyncSeriesHook<[Compilation]>
• 参数：
  • Compilation: 当前 Compilation 对象

#shouldEmit

返回值为一个布尔值，用于决定是否将资源写入到磁盘中。

• 类型： SyncBailHook<[Compilation], boolean>
• 参数：
  • Compilation: 当前 Compilation 对象

• 示例：

compiler.hooks.shouldEmit.tap('MyPlugin', compilation => {
  // 返回 true 以输出 output 结果，否则返回 false
  return true;
});

#emit

在产物输出到结果目录前执行。

• 类型： AsyncSeriesHook<[Compilation]>
• 参数：
  • Compilation: 当前 Compilation 对象

#afterEmit

输出产物到结果目录后执行。

• 类型： AsyncSeriesHook<[Compilation]>
• 参数：
  • Compilation: 当前 Compilation 对象

#done

当前 Compilation 处理完成时执行。

• 类型： AsyncSeriesHook<Stats>
• 参数：
  • Stats: 生成的 Stats 对象

#afterDone

当前 Compilation 处理完成且 done 钩子调用之后执行。

• 类型： SyncHook<Stats>
• 参数：
  • Stats: 生成的 Stats 对象

#failed

当前 Compilation 失败时调用。

• 类型： SyncHook<[Error]>

#invalid

当监听模式下的编译因文件变更而失效时执行。这个 hook 不会被复制到 child compiler 中。

• 类型： SyncHook<[string | null, number]>
• 参数：
  • fileName: 失效的文件路径
  • changeTime: 失效的文件修改时间戳

在触发重新编译时，这个 hook 可以用于获取变更的文件路径和修改时间，例如：

compiler.hooks.invalid.tap('MyPlugin', (fileName, changeTime) => {
  console.log(`Changed file: ${fileName}, change time: ${changeTime}`);
});

#watchClose

停止监听时调用。

• 类型： SyncHook<[]>

#shutdown

当前 Compiler 关闭时调用。

• Type: AsyncSeriesHook<[]>

#infrastructureLog

当基础设施日志被触发时调用，允许插件拦截、修改或处理日志消息。

此钩子提供了一种自定义 Rspack 基础设施日志的方法 - 你可以过滤特定的日志类型、添加自定义格式，或完全覆盖默认的日志行为。

如果钩子返回 true，将阻止默认的基础设施日志记录。如果返回 undefined，将继续执行默认的日志输出。

• 类型： SyncBailHook<[string, string, any[]], true | void>
• 参数：
  • name：logger 的名称
  • type：log 类型（例如 'log'、'warn'、'error' 等）
  • args：传递给 logger 方法的参数数组
• 示例：

class ExamplePlugin {
  apply(compiler) {
    compiler.hooks.infrastructureLog.tap('MyPlugin', (name, type, args) => {
      // 自定义日志逻辑
      if (type === 'error') {
        console.error(`[${name}] ERROR:`, ...args);
        return true; // 阻止默认日志输出
      }

      // 让其他日志类型使用默认行为
      return undefined;
    });
  }
}

查看 infrastructureLogging 了解更多关于基础设施日志的信息。