简体中文

Compilation 钩子

Compilation 钩子是 Rspack 插件的主要扩展方式，为开发者提供了介入构建流程各阶段的能力。

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

TIP

查看 Compilation 了解更多关于 Compilation 对象的信息。

INFO

Rspack 的主要编译逻辑运行在 Rust 侧。出于稳定性、性能、架构等因素，在使用钩子时，Rust 侧编译对象传输到 JavaScript 侧后，对 JavaScript 侧的修改不会被同步到 Rust 侧。因此绝大部分钩子为“只读”。

Overview

`buildModule`

只读

在模块被构建之前调用。

类型： SyncHook<[Module]>
参数：
- Module：模块实例

Module.ts

`executeModule`

只读

若存在编译期执行模块，将在模块被执行时调用。

类型： SyncHook<[ExecuteModuleArgument, ExecuteModuleContext]>
参数：
- ExecuteModuleArgument：模块运行参数
- ExecuteModuleContext：模块运行上下文

ExecuteModuleArgument.ts

ExecuteModuleContext.ts

`succeedModule`

只读

在模块成功构建后调用。

类型： SyncHook<[Module]>
参数：
- Module：模块实例

Module.ts

`finishModules`

只读

当所有模块都没有错误地构建完成时调用。

类型： AsyncSeriesHook<[Module[]]>
参数：
- Module[]：所有模块列表

Module.ts

`optimizeModules`

只读

在模块优化阶段开始时调用。

类型： SyncBailHook<[Module[]]>
参数：
- Module[]：所有模块列表

Module.ts

`seal`

停止接收新模块并开始优化前触发。

类型： SyncHook<[]>

`afterOptimizeModules`

只读

在模块优化完成之后调用。

类型： SyncBailHook<[Module[]]>
参数：
- Module[]：所有模块列表

Module.ts

`optimizeTree`

只读

在优化依赖树之前调用。

类型： AsyncSeriesHook<[Chunk[], Module[]]>
参数：
- Chunk[]：Chunk 列表：
- Module[]：模块列表

Chunk.ts

Module.ts

`optimizeChunkModules`

只读

在树优化之后，chunk 模块优化开始时调用。

类型： AsyncSeriesBailHook<[Chunk[], Module[]]>
参数：
- Chunk[]：Chunk 列表：
- Module[]：模块列表

Chunk.ts

Module.ts

`additionalTreeRuntimeRequirements`

在树运行时依赖计算完成后调用。

类型： SyncHook<[Chunk, Set<RuntimeGlobals>]>
参数：
- Chunk：Chunk 实例
- Set<RuntimeGlobals>：运行时依赖集合

可通过修改运行时依赖集合以添加额外的内置运行时模块：

rspack.config.mjs

export default {
  entry: './index.js',
  plugins: [
    {
      apply(compiler) {
        const { RuntimeGlobals } = compiler.rspack;
        compiler.hooks.thisCompilation.tap('CustomPlugin', compilation => {
          compilation.hooks.additionalTreeRuntimeRequirements.tap(
            'CustomPlugin',
            (_, set) => {
              // 添加访问 compilation 哈希值的运行时模块
              set.add(RuntimeGlobals.getFullHash);
            },
          );
        });
      },
    },
  ],
};

index.js

// 将打印 compilation 的哈希值
console.log(__webpack_require__.h);

`runtimeRequirementInTree`

Added in v1.0.6

在根据运行时依赖以添加运行时模块时调用。

类型： HookMap<SyncBailHook<[Chunk, Set<RuntimeGlobals>]>>
参数：
- Chunk：Chunk 实例
- Set<RuntimeGlobals>：运行时依赖集合

可通过修改运行时依赖集合以添加额外的内置运行时模块，也可通过 compilation.addRuntimeModule 添加自定义运行时模块：

rspack.config.mjs

export default {
  entry: './index.js',
  plugins: [
    {
      apply(compiler) {
        const { RuntimeGlobals, RuntimeModule } = compiler.rspack;
        class CustomRuntimeModule extends RuntimeModule {
          constructor() {
            super('custom');
          }

          generate() {
            const compilation = this.compilation;
            return `
            __webpack_require__.mock = function(file) {
              return ${RuntimeGlobals.publicPath} + "/subpath/" + file;
            };
          `;
          }
        }

        compiler.hooks.thisCompilation.tap('CustomPlugin', compilation => {
          compilation.hooks.runtimeRequirementInTree
            .for(RuntimeGlobals.ensureChunkHandlers)
            .tap('CustomPlugin', (chunk, set) => {
              // 添加访问 publicPath 的运行时模块
              set.add(RuntimeGlobals.publicPath);
              // 添加自定义运行时模块
              compilation.addRuntimeModule(chunk, new CustomRuntimeModule());
            });
        });
      },
    },
  ],
};

index.js

// 将打印 "/subpath/index.js"
console.log(__webpack_require__.mock('index.js'));

`runtimeModule`

在运行时模块被添加后调用。

类型： SyncHook<[RuntimeModule, Chunk]>
参数：
- RuntimeModule：运行时模块
- Chunk：Chunk 实例

可通过 source 字段修改该运行时模块生成的代码。

rspack.config.mjs

export default {
  plugins: [
    {
      apply(compiler) {
        const { RuntimeGlobals } = compiler.rspack;
        compiler.hooks.compilation.tap('CustomPlugin', compilation => {
          compilation.hooks.runtimeModule.tap(
            'CustomPlugin',
            (module, chunk) => {
              if (module.name === 'public_path' && chunk.name === 'main') {
                const originSource = module.source.source.toString('utf-8');
                module.source.source = Buffer.from(
                  `${RuntimeGlobals.publicPath} = "/override/public/path";\n`,
                  'utf-8',
                );
              }
            },
          );
        });
      },
    },
  ],
};

index.js

// 将打印 "/override/public/path"
console.log(__webpack_require__.p);

RuntimeModule.ts

`processAssets`

在产物输出之前进行修改产物。

类型： AsyncSeriesHook<Assets>
hook 参数：
- name: string — 插件的名称
- stage: Stage — 要处理的阶段（参考 Process assets stages）
参数：
- Assets: Record<string, Source>: 一个对象，其中 key 是 asset 的路径名，值是由 Source 表示的 asset 数据。

Source.ts

Process assets 示例

在 PROCESS_ASSETS_STAGE_ADDITIONAL 阶段输出一个新的 asset：

compiler.hooks.thisCompilation.tap('MyPlugin', compilation => {
  const { Compilation } = compiler.rspack;
  compilation.hooks.processAssets.tap(
    {
      name: 'MyPlugin',
      stage: Compilation.PROCESS_ASSETS_STAGE_ADDITIONAL,
    },
    assets => {
      const { RawSource } = compiler.rspack.sources;
      const source = new RawSource('This is a new asset!');
      compilation.emitAsset('new-asset.txt', source);
    },
  );
});

更新一个已经存在的 asset：

compiler.hooks.thisCompilation.tap('MyPlugin', compilation => {
  const { Compilation } = compiler.rspack;
  compilation.hooks.processAssets.tap(
    {
      name: 'MyPlugin',
      stage: Compilation.PROCESS_ASSETS_STAGE_ADDITIONS,
    },
    assets => {
      const asset = assets['foo.js'];
      if (!asset) {
        return;
      }

      const { RawSource } = compiler.rspack.sources;
      const oldContent = asset.source();
      const newContent = oldContent + '\nconsole.log("hello world!")';
      const source = new RawSource(newContent);

      compilation.updateAsset(assetName, source);
    },
  );
});

移除一个 asset：

compiler.hooks.thisCompilation.tap('MyPlugin', compilation => {
  const { Compilation } = compiler.rspack;
  compilation.hooks.processAssets.tap(
    {
      name: 'MyPlugin',
      stage: Compilation.PROCESS_ASSETS_STAGE_OPTIMIZE,
    },
    assets => {
      const assetName = 'unwanted-script.js';
      if (assets[assetName]) {
        compilation.deleteAsset(assetName);
      }
    },
  );
});

Process assets stages

下面是支持的 stage 列表，Rspack 会按由上至下的顺序依次执行这些 stages，请根据你需要进行的操作来选择合适的 stage。

PROCESS_ASSETS_STAGE_ADDITIONAL — 在编译中添加额外的 asset。
PROCESS_ASSETS_STAGE_PRE_PROCESS — asset 进行了基础的预处理。
PROCESS_ASSETS_STAGE_DERIVED — 从现有 asset 中派生新的 asset。
PROCESS_ASSETS_STAGE_ADDITIONS — 为现有的 asset 添加额外的内容，例如 banner 或初始代码。
PROCESS_ASSETS_STAGE_OPTIMIZE — 以通用的方式优化现有 asset。
PROCESS_ASSETS_STAGE_OPTIMIZE_COUNT — 优化现有 asset 的数量，例如，进行合并操作。
PROCESS_ASSETS_STAGE_OPTIMIZE_COMPATIBILITY — 优化现有 asset 的兼容性，例如添加 polyfills 或者 vendor prefixes。
PROCESS_ASSETS_STAGE_OPTIMIZE_SIZE — 优化现有 asset 的大小，例如进行压缩或者删除空格。
PROCESS_ASSETS_STAGE_DEV_TOOLING — 为 asset 添加开发者工具，例如，提取 source map。
PROCESS_ASSETS_STAGE_OPTIMIZE_INLINE — 将 asset 内联到其他 asset 中来优化现有 asset 数量。
PROCESS_ASSETS_STAGE_SUMMARIZE — 整理现有 asset 列表。
PROCESS_ASSETS_STAGE_OPTIMIZE_HASH — 优化 asset 的 hash 值，例如，生成基于 asset 内容的真实 hash 值。
PROCESS_ASSETS_STAGE_OPTIMIZE_TRANSFER — 优化已有 asset 的转换操作，例如对 asset 进行压缩，并作为独立的 asset。
PROCESS_ASSETS_STAGE_ANALYSE — 分析已有 asset。
PROCESS_ASSETS_STAGE_REPORT — 创建用于上报的 asset。

`afterProcessAssets`

只读

在 processAssets hook 无错误执行后调用。

类型： SyncHook<Assets>
参数：
- Assets: Record<string, Source>：产物资源映射表

Source.ts

示例：

compilation.hooks.afterProcessAssets.tap('MyPlugin', assets => {
  console.log('assets', Object.keys(assets));
});

`afterSeal`

只读

在 seal 阶段结束后调用。

类型： AsyncSeriesHook<[]>

`chunkHash`

只读

触发来为每个 chunk 生成 hash。

类型： SyncHook<[Chunk, Hash]>
参数：
- Chunk：Chunk 实例
- Hash：Chunk 哈希实例

Chunk.ts

Hash.ts

`chunkAsset`

只读

一个 chunk 中的一个 asset 被添加到 compilation 时调用。

类型： SyncHook<[Chunk, string]>
参数：
- Chunk：Chunk 实例
- string：产物文件名

Chunk.ts

`childCompiler`

只读

创建子 compiler 之后调用。

类型： SyncHook<[Compiler, string, number]>
参数：
- Compiler：子编译实例：
- string：子编译名称
- number：子编译索引

Compiler.ts

`statsPreset`

只读

当使用预设 stats 配置时触发。接收一个 stats 配置对象，当插件管理 stats 预设配置时，它应当在配置对象上仔细地修改，而非直接替换整个配置对象。

类型： SyncHook<[Partial<StatsOptions>, CreateStatsOptionsContext]>
参数：
- Partial<StatsOptions>：Stats 配置
- CreateStatsOptionsContext：Stats 上下文

以如下插件为例：

compilation.hooks.statsPreset.for('my-preset').tap('MyPlugin', options => {
  if (options.all === undefined) options.all = true;
});

该插件确保对于预设 "my-preset"，如果 all 选项未定义，则默认为 true。

StatsOptions.ts

CreateStatsOptionsContext.ts

`statsNormalize`

只读

此钩子用于将选项对象转换为便于后续钩子使用的格式。它还确保缺失的选项被设置为默认值。

类型： SyncHook<[Partial<StatsOptions>, CreateStatsOptionsContext]>
参数：
- Partial<StatsOptions>：Stats 配置
- CreateStatsOptionsContext：Stats 上下文

以如下插件为例：

compilation.hooks.statsNormalize.tap('MyPlugin', options => {
  if (options.myOption === undefined) options.myOption = [];

  if (!Array.isArray(options.myOption)) options.myOptions = [options.myOptions];
});

在这个插件中，如果 myOption 缺失，会将其设置为 []。此外，它确保 myOption 始终是一个数组，即使它最初被定义为单个值。

StatsOptions.ts

CreateStatsOptionsContext.ts

`statsFactory`

只读

此钩子提供了对 StatsFactory 的访问，以调用其钩子。该类用于构造 Stats 对象。

类型： SyncHook<[StatsFactory, StatsOptions]>
参数：
- StatsFactory：Stats 工厂实例，详见 Stats Factory 钩子
- StatsOptions：Stats 配置

StatsFactory.ts

StatsOptions.ts

`statsPrinter`

只读

此钩子提供了对 StatsPrinter 的访问，以调用其钩子。该类用于打印 Stats 信息。

类型： SyncHook<[StatsPrinter, StatsOptions]>
参数：
- StatsPrinter：Stats 打印实例，详见 Stats Printer 钩子
- StatsOptions：Stats 配置

StatsPrinter.ts

StatsOptions.ts

#Compilation 钩子

#Overview

#buildModule

#executeModule

#succeedModule

#finishModules

#optimizeModules

#seal

#afterOptimizeModules

#optimizeTree

#optimizeChunkModules

#additionalTreeRuntimeRequirements

#runtimeRequirementInTree

#runtimeModule

#processAssets

#Process assets 示例

#Process assets stages

#afterProcessAssets

#afterSeal

#chunkHash

#chunkAsset

#childCompiler

#statsPreset

#statsNormalize

#statsFactory

#statsPrinter

Compilation 钩子

Overview

`buildModule`

`executeModule`

`succeedModule`

`finishModules`

`optimizeModules`

`seal`

`afterOptimizeModules`

`optimizeTree`

`optimizeChunkModules`

`additionalTreeRuntimeRequirements`

`runtimeRequirementInTree`

`runtimeModule`

`processAssets`

Process assets 示例

Process assets stages

`afterProcessAssets`

`afterSeal`

`chunkHash`

`chunkAsset`

`childCompiler`

`statsPreset`

`statsNormalize`

`statsFactory`

`statsPrinter`