Webpack教程系列（十三）：Webpack Plugin开发详解

1. 为什么需要自定义插件？

Webpack 插件是扩展 Webpack 功能的核心机制。通过自定义插件，我们可以：

  • 干预打包过程：在打包的任意阶段执行自定义逻辑。
  • 优化构建结果：例如压缩代码、生成资源清单等。
  • 集成外部工具：例如自动上传文件到 CDN、生成 HTML 报告等。

本文将详细介绍如何开发一个 Webpack 插件。

2. 插件的基本结构

一个 Webpack 插件是一个 JavaScript 类，需要实现 apply 方法。apply 方法接收一个 compiler 对象，用于访问 Webpack 的内部钩子。

2.1 插件示例

以下是一个简单的插件示例：

1
2
3
4
5
6
7
8
9
class MyPlugin {
  apply(compiler) {
    compiler.hooks.done.tap('MyPlugin', stats => {
      console.log('打包完成！');
    });
  }
}

module.exports = MyPlugin;

2.2 使用插件

在 webpack.config.js 中使用插件：

1
2
3
4
5
6
7
const MyPlugin = require('./MyPlugin');

module.exports = {
  plugins: [
    new MyPlugin()
  ]
};

3. Webpack 的生命周期钩子

Webpack 提供了丰富的生命周期钩子，插件可以通过这些钩子干预打包过程。以下是一些常用的钩子：

钩子名称 触发时机 示例用途
entryOption 处理入口配置时 修改入口配置
compile 开始编译时 初始化自定义逻辑
compilation 创建新的编译对象时 干预模块处理逻辑
emit` 生成资源到输出目录前 修改输出资源
done` 打包完成时 输出打包结果信息

4. 开发一个简单的自定义插件

生成一个 JSON 格式的文件，记录所有资源文件的名称及其大小。

4.1 插件代码

在项目根目录下创建 ResourceListPlugin.js：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
const fs = require('fs');
const path = require('path');

class ResourceListPlugin {
  constructor(options) {
    this.options = options || { filename: 'resource-list.json' };
  }

  apply(compiler) {
    compiler.hooks.emit.tapAsync('ResourceListPlugin', (compilation, callback) => {
      const assets = compilation.assets;
      const resourceList = {};

      // 遍历所有资源
      Object.keys(assets).forEach(assetName => {
        resourceList[assetName] = assets[assetName].size();
      });

      // 生成资源清单文件
      const outputPath = compilation.options.output.path;
      const filePath = path.join(outputPath, this.options.filename);
      const content = JSON.stringify(resourceList, null, 2);

      // 将文件添加到输出资源中
      compilation.assets[this.options.filename] = {
        source: () => content,
        size: () => content.length
      };

      callback();
    });
  }
}

module.exports = ResourceListPlugin;

4.2 使用插件

在 webpack.config.js 中使用插件：

1
2
3
4
5
6
7
const ResourceListPlugin = require('./ResourceListPlugin');

module.exports = {
  plugins: [
    new ResourceListPlugin({ filename: 'assets.json' })
  ]
};

4.3 运行结果

打包完成后，dist 目录下会生成一个 assets.json 文件，内容如下：

1
2
3
4
{
  "main.js": 1024,
  "index.html": 512
}

5. 开发一个复杂的自定义插件

在 Webpack 编译后，将静态资源上传到指定的 CDN，并更新 HTML 文件中的资源链接为 CDN 地址。

5.1 插件代码

在项目根目录下创建 UploadToCDNPlugin.js：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
const fs = require('fs');
const path = require('path');
const axios = require('axios');
const HtmlWebpackPlugin = require('html-webpack-plugin');

class UploadToCDNPlugin {
  constructor(options) {
    this.options = options || {};
    this.options.cdnUrl = this.options.cdnUrl || 'https://cdn.wyxup.top'; // 默认 CDN 地址
    this.options.assetsDir = this.options.assetsDir || path.resolve(__dirname, 'dist/assets'); // 本地存储目录
  }

  apply(compiler) {
    // Step 1: 在 emit 阶段上传静态资源
    compiler.hooks.emit.tapAsync('UploadToCDNPlugin', (compilation, callback) => {
      const assets = compilation.assets;

      // 上传资源到 CDN
      const uploadPromises = Object.keys(assets).map(async (assetName) => {
        const asset = assets[assetName];
        const filePath = path.join(compilation.options.output.path, assetName);
        const fileContent = asset.source();
        
        // 上传文件到 CDN
        try {
          const response = await axios.put(`${this.options.cdnUrl}/${assetName}`, fileContent, {
            headers: {
              'Content-Type': 'application/octet-stream',
            },
          });
          console.log(`上传成功: ${assetName} 至 CDN`);
          return { assetName, cdnUrl: `${this.options.cdnUrl}/${assetName}` };
        } catch (error) {
          console.error(`上传失败: ${assetName}`, error);
        }
      });

      // 等待所有上传完成
      Promise.all(uploadPromises)
        .then((cdnUrls) => {
          // 将 CDN URL 替换到 HTML 中
          this.replaceHtmlWithCdnUrls(compilation, cdnUrls);
          callback();
        })
        .catch((err) => {
          console.error('上传资源到 CDN 失败', err);
          callback();
        });
    });
  }

  // Step 2: 替换 HTML 中的本地链接为 CDN 链接
  replaceHtmlWithCdnUrls(compilation, cdnUrls) {
    const htmlPlugin = compilation.plugins.find(plugin => plugin instanceof HtmlWebpackPlugin);
    if (htmlPlugin) {
      const htmlFile = compilation.assets[htmlPlugin.options.filename];

      let htmlContent = htmlFile.source();

      cdnUrls.forEach(({ assetName, cdnUrl }) => {
        // 替换本地资源的路径为 CDN 路径
        const regex = new RegExp(`(["'])${assetName}\\1`, 'g');
        htmlContent = htmlContent.replace(regex, `\$1${cdnUrl}\$1`);
      });

      // 更新 HTML 文件内容
      compilation.assets[htmlPlugin.options.filename] = {
        source: () => htmlContent,
        size: () => htmlContent.length,
      };
    }
  }
}

module.exports = UploadToCDNPlugin;

5.2 使用插件

在 webpack.config.js 中使用插件：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
const path = require('path');
const HtmlWebpackPlugin = require('html-webpack-plugin');
const UploadToCDNPlugin = require('./UploadToCDNPlugin'); 

module.exports = {
  entry: './src/index.js',
  output: {
    filename: '[name].[contenthash].js',
    path: path.resolve(__dirname, 'dist'),
    publicPath: '/', // 输出路径
  },
  plugins: [
    new HtmlWebpackPlugin({
      template: './src/index.html', // 模板文件路径
    }),
    new UploadToCDNPlugin({
      cdnUrl: 'https://cdn.wyxup.top', // CDN 地址
      assetsDir: path.resolve(__dirname, 'dist/assets'), // 本地资源目录
    }),
  ]
};

6. 插件的测试与调试

6.1 测试插件

编写单元测试，验证插件的功能。可以使用 jest 或 mocha 等测试框架。

6.2 调试插件

在插件代码中添加 console.log 或使用 debugger 语句，结合 Chrome DevTools 进行调试。

7. 总结

本文详细介绍了如何开发一个 Webpack 插件，包括插件的基本结构、生命周期钩子、自定义插件的开发与使用。通过自定义插件，我们可以灵活地扩展 Webpack 的功能，满足各种复杂的开发需求。

在下一篇文章中，我们将深入探讨 Webpack 的 Loader 开发，学习如何编写自定义 Loader。

预告：

  • 下一篇：Webpack Loader 开发详解