Plugin API

插件是 webpack 生态的关键部分， 它为社区用户提供了一种强有力的方式来直接触及 webpack 的编译过程(compilation process)。 插件能够 hook 到每一个编译(compilation)中发出的关键事件中。 在编译的每个阶段中，插件都拥有对 compiler 对象的完全访问能力， 并且在合适的时机，还可以访问当前的 compilation 对象。

让我们首先从 tapable 工具开始， 它为 webpack 插件接口提供了核心能力的。

Tapable

这个小型库是 webpack 的一个核心工具，但也可用于其他地方， 以提供类似的插件接口。 在 webpack 中的许多对象都扩展自 Tapable 类。 它对外暴露了 tap，tapAsync å’Œ tapPromise 等方法， 插件可以使用这些方法向 webpack 中注入自定义构建的步骤，这些步骤将在构建过程中触发。

请查阅文档了解更多知识。 理解上面的的三种 tap 方法， 以及提供这些方法的钩子(hooks)对于编写插件来说是至关重要的。 那些扩展自 Tapable 的对象（例如：compiler）， 以及其提供的钩子(hooks)和每个钩子的类型（例如：同步钩子(SyncHook)）值得关注。

插件类型

根据使用不同的钩子(hooks)å’Œ tap 方法， 插件可以以多种不同的方式运行。 这个工作方式与 Tapable 提供的钩子(hooks)密切相关。 compiler hooks 分别记录了 Tapable 内在的钩子， 并指出哪些 tap 方法可用。

所以，依赖于使用的 tap 方法的不同， 插件可能会以不同的方式运行。 例如：当你钩入到 编译(compile) 阶段时，只有同步的 tap 方法可以使用。

compiler.hooks.compile.tap('MyPlugin', (params) => {
  console.log('以同步方式触及 compile 钩子。');
});

然而，对于可以使用 AsyncHook çš„ run 阶段， 则需使用 tapAsync 或 tapPromise（以及 tap）方法。

compiler.hooks.run.tapAsync(
  'MyPlugin',
  (source, target, routesList, callback) => {
    console.log('以异步方式触及运行钩子。');
    callback();
  }
);

compiler.hooks.run.tapPromise('MyPlugin', (source, target, routesList) => {
  return new Promise((resolve) => setTimeout(resolve, 1000)).then(() => {
    console.log('以异步的方式触发具有延迟操作的钩子。');
  });
});

compiler.hooks.run.tapPromise(
  'MyPlugin',
  async (source, target, routesList) => {
    await new Promise((resolve) => setTimeout(resolve, 1000));
    console.log('以异步的方式触发具有延迟操作的钩子。');
  }
);

这些需求(story)的含义在于， 我们可以有多种方式 hook 到 compiler 中，可以让各种插件都以合适的方式去运行。

自定义钩子

为了便于其他插件的编译过程中可以 tap 到， 你可以这样做：

1. Create a module-scope WeakMap for compilation hooks:

   const compilationHooks = new WeakMap<Compilation, MyHooks>();
   
   interface MyHooks {
     custom: SyncHook<[number, string]>;
   }

2. 在插件中创建一个静态方法：

   static getCompilationHooks(compilation: Compilation) : MyHooks {
     let hooks = compilationHooks.get(compilation);
     if(hooks === undefined) {
       compilationHooks.set(compilation, hooks = {
         custom: new SyncHook()
       });
     }
     return hooks;
   }

3. 像下面这样在你的插件中调用钩子函数：

   const hooks = MyPlugin.getCompilationHooks(compilation);
   
   hooks.custom.call(1, 'hello');

4. 其他插件也可以访问你的自定义钩子函数：

   import MyPlugin from 'my-plugin';
   
   const hooks = MyPlugin.getCompilationHooks(compilation);
   
   hooks.custom.tap('OtherPlugin', (n, s) => {
     // magic
   });

再次声明， 查看 tapable 文档 来了解更多不同的钩子类(hook class)，以及它们是如何工作的。

进度报告

插件能够通过 ProgressPlugin 这个在默认情况下将信息打印到标准错误输出(stderr)的插件来进行进度报告。如果想要使用这个功能，只需要在使用 webpack CLI 的时候传入 --progress 参数。

如果想要自定义打印输出，只需要传递不同的参数到 ProgressPlugin çš„ reportProgress 方法。

如果想要报告进度，插件必须在 tap 到 hook 的时候使用 context: true 选项。

compiler.hooks.emit.tapAsync(
  {
    name: 'MyPlugin',
    context: true,
  },
  (context, compiler, callback) => {
    const reportProgress = context && context.reportProgress;
    if (reportProgress) reportProgress(0.95, 'Starting work');
    setTimeout(() => {
      if (reportProgress) reportProgress(0.95, 'Done work');
      callback();
    }, 1000);
  }
);

reportProgress 方法在被调用的时候会传入以下的参数：

reportProgress(percentage, ...args);

• percentage：此参数未使用。作为代替，ProgressPlugin 插件会基于当前的钩子(hook)计算进度。
• ...args：任意数量的字符串，这些字符串会传递给 ProgressPlugin 插件并报告给用户。

注意：只有 compiler å’Œ compilation 钩子的子集才支持 reportProgress 方法。请查看 ProgressPlugin 了解更多信息。

日志

日志的 API 在 webpack 4.37 版本后提供支持。当 logging 在 统计配置(stats configuration)中可用和(或)当 infrastructure logging 可用的时候，插件会通过各自的记录格式(stats，infrastructure)打印信息。

• 插件可以使用 compilation.getLogger('PluginName') 来做记录。这种形式的记录保存在统计数据(Stats)中并做相应的格式化。它能够被用户过滤和导出。
• 插件也可以使用 compilation.getInfrastructureLogger('PluginName') 来做记录。使用 infrastructure 的形式并不会被保存在统计数据(Stats)中，因此也不会被格式化。它通常直接将记录载入到 console/dashboard/GUI 中。它能够被用户过滤。
• 插件也可以使用特殊的降级逻辑 compilation.getLogger ? compilation.getLogger('PluginName') : console 来检测是否支持记录，以此来在不支持 compilation.getLogger 方法的旧版本 webpack 中提供降级方法。

下一步

查看 compiler hooks 部分， 了解所有可用的 compiler 钩子以及它们提供的参数的详细列表。