# 自定义plugin篇|博客系列

> 本文详细介绍了如何自定义Webpack插件，包括插件的基本结构、使用方式、与loader的区别及其在Webpack构建流程中的作用，帮助前端开发者深入理解和实现自定义Webpack插件。

- 原文：https://feinterview.poetries.top/docs/fe-blog-docs/blog-docs/webpack/-%E8%87%AA%E5%AE%9A%E4%B9%89plugin%E7%AF%87
- 来源：前端进阶之旅（feinterview.poetries.top）
- 更新：2025.10.25
- 可见范围：免费部分

---

## 前期准备

### 从使用的角度来看插件

好了，我已经准备好阅读的这篇文章然后写一个炒鸡牛x的插件了，赶紧的。

额，等等，在这之前我们不是得知道需要怎么去做吗？我们总是听到的插件插件的，它到底是个啥啊？

对象？函数？类？

小伙伴们不妨结合我们已经用过的一些插件来猜猜，比如`HtmlWebpackPlugin`，我们会这样使用它：

```javascript
module.exports = {
  plugins: [
    new HtmlWebpackPlugin({
      title: 'custom-plugin'
    })
  ]
}
```

可以看到，这很明显的就是个构造函数，或者是一个类嘛。我们使用`new`就可以实例化一个插件的对象。并且，这个函数或者类是可以让我们传递参数进去的。

那你脑子里是不是已经脑补出一个轮廓了呢？

```javascript
function CustomPlugin (options) {}

// or
class CustomPlugin {
  constructor (options) {}
}
```

### 从构建的角度来看插件

知道了`plugin`大概的轮廓，让我们从构建的角度来看看它。插件不同于`loader`一个很大的区别就是，`loader`它是一个转换器，它只专注于**转换**这一个领域，例如`babel-loader`能将`ES6+`的代码转换为`ES5`或以下，以此来保证兼容性，那么它是运行在打包之前的。

而`plugin`呢？你会发现市场上有各种让人眼花缭乱的插件，它可能运行在打包之前，也可能运行在打包的过程中，或者打包完成之后。总之，**它不局限于打包，资源的加载，还有其它的功能**。所以它是在整个编译周期都起作用。

那么如果让我们站在一个编写插件者的角度上来看的话，是不是在编写的时候需要明确两件事情：

- 我要如何拿到完整的`webpack`环境配置呢？因为我在编写插件的时候肯定是要与`webpack`的主环境结合起来的
- 我如何告诉`webpack`我的插件是在什么时候发挥作用呢？在打包之前？还是之后？也就是我们经常听到的钩子。

所以这时候我们就得清楚这几个硬知识点：

- `compiler` 对象代表了完整的 webpack 环境配置。这个对象在启动 webpack 时被一次性建立，并配置好所有可操作的设置，包括 options，loader 和 plugin。当在 webpack 环境中应用一个插件时，插件将收到此 compiler 对象的引用。可以使用它来访问 webpack 的主环境。

- `compilation` 对象代表了一次资源版本构建。当运行 webpack 开发环境中间件时，每当检测到一个文件变化，就会创建一个新的 compilation，从而生成一组新的编译资源。一个 compilation 对象表现了当前的模块资源、编译生成资源、变化的文件、以及被跟踪依赖的状态信息。compilation 对象也提供了很多关键时机的回调，以供插件做自定义处理时选择使用。
- 钩子的本质其实就是事件

### 案例准备

老规矩，为了能更好的让我们掌握本章的内容，我们需要本地创建一个案例来进行讲解。

创建项目的这个过程我就快速的用指令来实现一下哈：

```javascript
mkdir webpack-custom-plugin && cd webpack-custom-plugin
npm init -y
cnpm i webpack webpack-cli clean-webpack-plugin html-webpack-plugin --save-dev
touch webpack.config.js
mkdir src && cd src
touch index.js
```

(`mkdir`：创建一个文件夹；`touch`：创建一个文件)

OK👌，此时项目目录变成了：

```javascript
 webpack-custom-plugin
    |- package.json
    |- webpack.config.js
    |- /src
      |- index.js
```

接着让我们给`src/index.js`随便加点东西意思一下，省得太空了：

*src/index.js*

```javascript
function createElement () {
  const element = document.createElement('div')
  element.innerHTML = '孔子曰：中午不睡，下午崩溃!孟子曰：孔子说的对!';

  return element
}
document.body.appendChild(createElement())
```

`webpack.config.js`也简单的来配置一下吧，这些应该都是基础了，之前有详细说过了哟：

```javascript
const path = require('path');
const HtmlWebpackPlugin = require('html-webpack-plugin');
const { CleanWebpackPlugin } = require('clean-webpack-plugin');

module.exports = {
  entry: './src/index.js',
  output: {
    filename: '[name].bundle.js',
    path: path.resolve(__dirname, 'dist')
  },
  plugins: [
    new HtmlWebpackPlugin({
      title: 'custom-plugin'
    }),
    new CleanWebpackPlugin()
  ]
}
```

> `clean-webpack-plugin`插件会在我们每次打包之前自动清理掉旧的`dist`文件夹

另外还需要在`package.json`中配置一条打包指令哈：

```javascript
{
  "script": {
    "build": "webpack --mode development"
  }
}
```

这里的`"webpack"`实际上是`"webpack --config webpack.config.js"`的缩写，这点在基础篇中也有说到咯。

`--mode development`就是指定一下环境为开发环境，因为我们后续可能有需要看到打包之后的代码内容，如果指定了为`production`的话，那么`webpack`它会自动开启`UglifyJS`的也就是会对我们打包成功之后的代码进行压缩输出，那一坨一坨的代码我们就不利于我们查看了。

## No1-webpack-plugin案例

好的了，基本工作已经准备完毕了，让我们动手来编写我们的第一个插件吧。

这个插件案例主要是为了帮助你了解插件大概的创建流程。

### 传统形式的compiler.plugin

从易到难，让我们来实现这么一个简单的功能：

- 当我们在完成打包之后，控制台会输出一个`"good boy!"`

在刚刚的案例目录中新建一个`plugins`文件夹，然后在里面创建上我们的第一个插件: `No1-webpack-plugin`：

```diff
 webpack-custom-plugin
  |- package.json
  |- webpack.config.js
  |- /src
    |- index.js
+ |- /plugins
+   |-No1-webpack-plugin.js
```

现在依照前面所说的插件的结构，以及我们的需求，可以写出以下代码：

*plugins/No1-webpack-plugin.js*:

```javascript
// 1. 创建一个构造函数
function No1WebpackPlugin (options) {
  this.options = options
}
// 2. 重写构造函数原型对象上的 apply 方法
No1WebpackPlugin.prototype.apply = function (compiler) {
  compiler.plugin('done', () => {
    console.log(this.options.msg)
  })
}
// 3. 将我们的自定义插件导出
module.exports = No1WebpackPlugin;
```

接着，让我们来看看如何使用它，也就是：

*webpack.config.js*:

```diff
const path = require('path');
const HtmlWebpackPlugin = require('html-webpack-plugin');
const { CleanWebpackPlugin } = require('clean-webpack-plugin');
+ const No1WebpackPlugin = require('./plugins/No1-webpack-plugin');

module.exports = {
  entry: './src/index.js',
  output: {
    filename: '[name].bundle.js',
    path: path.resolve(__dirname, 'dist')
  },
  plugins: [
    new HtmlWebpackPlugin({
      title: 'custom-plugin'
    }),
    new CleanWebpackPlugin(),
+   new No1WebpackPlugin({ msg: 'good boy!' })
  ]
}
```

OK👌，代码已经编写完啦，快`npm run build`一下看看效果吧：

![](https://s.poetries.top/gitee/2020/09/202.png)

可以看到，控制台已经在夸你`"good boy!"`了😄。

那么让我们回到刚刚的那段自定义插件的代码中：

*plugins/No1-webpack-plugin.js*:

```javascript
// 1. 创建一个构造函数
function No1WebpackPlugin (options) {
  this.options = options
}
// 2. 在构造函数原型对象上定义一个 apply 方法
No1WebpackPlugin.prototype.apply = function (compiler) {
  compiler.plugin('done', () => {
    console.log(this.options.msg)
  })
}
// 3. 将我们的自定义插件导出
module.exports = No1WebpackPlugin;
```

注意到这里，我们一共是做了这么三件事情，也就是我在代码中的注释。

很显然，为了能拿到`webpack.config.js`中我们传递的那个参数，也就是`{ msg: 'good boy!' }`，我们需要在构造函数中定义一个实例对象上的属性`options`。

并且在`prototype.apply`中呢：

- 我们需要调用`compiler.plugin()`并传入第一个参数来指定我们的插件是发生在哪个阶段，也就是这里的`"done"`(一次编译完成之后，即打包完成之后)；
- 在这个阶段我们要做什么事呢？就可以在它的第二个参数回调函数中来写了，请注意这里我们的回调函数是一个箭头函数哦，这也是能够保证里面的`this`获取到的是我们的实例对象，也就是为了能保证我们拿到`options`，并成功的打印出`msg`

所以，现在你的思维是不是已经很清晰了呢？我们想要编写一个插件，只需要这么几步：

1. 明确你的插件是要怎么调用的，需不需要传递参数(对应着`webpack.config.js`中的配置)；
2. 创建一个构造函数，以此来保证用它能创建一个个插件实例；
3. 在构造函数原型对象上定义一个 apply 方法，并在其中利用`compiler.plugin`注册我们的自定义插件。

那么除了用构造函数的方式来创建插件，是否也可以用类呢？让我们一起来试试，将刚刚的代码改动一下：

*plugins/No1-webpack-plugin.js*:

```javascript
// // 1. 创建一个构造函数
// function No1WebpackPlugin (options) {
//   this.options = options
// }
// // 2. 重写构造函数原型对象上的 apply 方法
// No1WebpackPlugin.prototype.apply = function (compiler) {
//   compiler.plugin('done', () => {
//     console.log(this.options.msg)
//   })
// }
class No1WebpackPlugin {
  constructor (options) {
    this.options = options
  }
  apply (compiler) {
    compiler.plugin('done', () => {
      console.log(this.options.msg)
    })
  }
}
// 3. 将我们的自定义插件导出
module.exports = No1WebpackPlugin;
```

这时候你执行打包指令效果也是一样的哈。这其实也很好理解，`class`它不就是咱们构造函数的一个语法糖吗，所以它肯定也可以用来实现一个插件啦。

不过不知道小伙伴们注意到了，在我们刚刚输出`"good boy!"`的上面，还有一段小小的警告：

![](https://s.poetries.top/gitee/2020/09/203.png)

它告诉我们`Tabable.plugin`这种的调用形式已经被废弃了，请使用新的`API`，也就是`.hooks`来替代`.plugin`这种形式。

但并不是说上面的文档就不能看了，我们依然还是可以通过阅读它来了解更多插件相关的知识。

### 推荐使用compiler.hooks

既然官方都推荐我们用`compiler.hooks`了，那我们就遵循呗。不过如果你直接去看[Plugin API](https://www.webpackjs.com/api/plugins/#tapable)的话对新手来说好像又有点绕，里面的`Tapable`、`compiler`、`compile`、`compilation`它们直接到底是存在怎样的关系呢？

没关系都会依次的进行讲解。

现在让我们将`No1-webpack-plugin`使用`compiler.hooks`改造一下吧：

*plugins/No1-webpack-plugin.js*:

```javascript
// 第一版
// function No1WebpackPlugin (options) {
//   this.options = options
// }
// No1WebpackPlugin.prototype.apply = function (compiler) {
//   compiler.plugin('done', () => {
//     console.log(this.options.msg)
//   })
// }
// 第二版
// class No1WebpackPlugin {
//   constructor (options) {
//     this.options = options
//   }
//   apply (compiler) {
      // compiler.plugin('done', () => {
      //   console.log(this.options.msg)
      // })
//   }
// }
// 第三版
function No1WebpackPlugin (options) {
  this.options = options
}
No1WebpackPlugin.prototype.apply = function (compiler) {
  compiler.hooks.done.tap('No1', () => {
    console.log(this.options.msg)
  })
}
module.exports = No1WebpackPlugin;
```

可以看到，第三版中，关键点就是在于：

```javascript
compiler.hooks.done.tap('No1', () => {
  console.log(this.options.msg)
})
```

它替换了我们之前的：

```javascript
compiler.plugin('done', () => {
  console.log(this.options.msg)
})
```

让我们来拆分一下`compiler.hooks.done.tap('No1', () => {})`：

- `compiler`：一个扩展至`Tapable`的对象
- `compiler.hooks`：`compiler`对象上的一个属性，允许我们使用不同的钩子函数
- `.done`：`hooks`中常用的一种钩子，表示在一次编译完成后执行，它有一个回调参数`stats`(暂时没用上)
- `.tap`：表示可以注册同步的钩子和异步的钩子，而在此处因为`done`属于异步`AsyncSeriesHook`类型的钩子，所以这里表示的是注册`done`异步钩子。
- `.tap('No1')`：`tap()`的第一个参数`'No1'`，其实`tap()`这个方法它的第一个参数是可以允许接收一个**字符串**或者一个**Tap**类的对象的，不过在此处我们不深究，你先随便传一个字符串就行了，我把它理解为这次调用钩子的方法名。

所以让我们连起来理解这段代码的意思就是：

1. 在程序执行`new No1WebpackPlugin()`的时候，会初始化一个插件实例且调用其原型对象上的`apply`方法
2. 该方法会告诉`webpack`当你在一次编译完成之后，得执行一下我的箭头函数里的内容，也就是打印出`msg`

现在我们虽然会写一个简单的插件了，但是对于上面的一些对象、属性啥的好像还不是很懂耶。想要一口气吃完一头大象🐘是有点难的哦(而且那样也是犯法的)，所以接下来让我们来大概了解一下这些`Tapable`、`compiler`等等的东西是做什么的😊。

## Tapable

首先是`Tapable`这个东西，我看了一下网上有很多对它的描述：

1. tapable 这个小型 library 是 webpack 的一个核心工具
2. Webpack 的 Tapable 事件流机制保证了插件的有序性，使得整个系统扩展性良好
3. Tapable 为 webpack 提供了统一的插件接口（钩子）类型定义，它是 webpack 的核心功能库、

当然这些说法肯定都是对的哈，所以总结一下：

- 简单来说Tapable就是webpack用来创建钩子的库，为webpack提供了插件接口的支柱。

其实如果你去看了它[Git上的文档](https://github.com/webpack/tapable)的话，它就是暴露了9个`Hooks`类，以及3种方法(`tap、tapAsync、tapPromise`)，可用于为插件创建钩子。

![](https://s.poetries.top/gitee/2020/09/205.png)

9种`Hooks`类与3种方法之间的关系：

- `Hooks`类表示的是你的钩子是哪一种类型的，比如我们上面用到的`done`，它就属于`AsyncSeriesHook`这个类
- `tap、tapAsync、tapPromise`这三个方法是用于注入不同类型的自定义构建行为，因为我们的钩子可能有同步的钩子，也可能有异步的钩子，而我们在注入钩子的时候就得选对这三种方法了。

对于`Hooks`类你大可不必全都记下，一般来说你只需要知道我们要用的每种钩子它们实际上是有类型区分的，而区分它们的就是`Hooks`类。

如果你想要清楚它们之前的区别的话，这里也有找到一个解释的比较清楚的总结：

`Sync*`

- SyncHook --> 同步串行钩子，不关心返回值
- SyncBailHook  --> 同步串行钩子，如果返回值不为null 则跳过之后的函数
- SyncLoopHook --> 同步循环，如果返回值为true 则继续执行，返回值为false则跳出循环
- SyncWaterfallHook --> 同步串行，上一个函数返回值会传给下一个监听函数

`Async*`

- AsyncParallel*：异步并发
  - AsyncParallelBailHook -->  异步并发，只要监听函数的返回值不为 null，就会忽略后面的监听函数执行，直接跳跃到callAsync等触发函数绑定的回调函数，然后执行这个被绑定的回调函数
  - AsyncParallelHook --> 异步并发，不关心返回值
- AsyncSeries*：异步串行
  - AsyncSeriesHook --> 异步串行，不关心callback()的参数
  - AsyncSeriesBailHook --> 异步串行，callback()的参数不为null，就会忽略后续的函数，直接执行callAsync函数绑定的回调函数
  - AsyncSeriesWaterfallHook --> 异步串行，上一个函数的callback(err, data)的第二个参数会传给下一个监听函数

(总结来源：[XiaoLu-写一个简单webpack plugin所引发的思考](https://juejin.im/post/5e6e2b326fb9a07cb24ab84c))

而对于这三种方法，我们必须得知道它们分别是做什么用的：

- `tap`：可以注册同步钩子也可以注册异步钩子
- `tapAsync`：回调方式注册异步钩子
- `tapPromise`：`Promise`方式注册异步钩子

![](https://s.poetries.top/gitee/2020/09/206.png)

---

> 以上是免费部分。完整内容需要「前端进阶之旅」会员，原文：https://feinterview.poetries.top/docs/fe-blog-docs/blog-docs/webpack/-%E8%87%AA%E5%AE%9A%E4%B9%89plugin%E7%AF%87
