Webpack Plugin 开发完全指南

1. 什么是 Webpack Plugin？#

Webpack Plugin 本质上是一个包含 apply 方法的类或对象。Plugin 可以在 Webpack 构建流程的各个阶段注入自定义逻辑。

1.1 最简单的 Plugin#

1
class MyPlugin {
2
  // apply方法会被webpack调用
3
  apply(compiler) {
4
    console.log('MyPlugin is working!')
5

6
    // compiler是webpack的核心对象
7
    // 可以通过hooks注册回调
8
  }
9
}
10

11
module.exports = MyPlugin

1.2 使用 Plugin#

1
const MyPlugin = require('./MyPlugin')
2

3
module.exports = {
4
  plugins: [
5
    new MyPlugin()
6
  ]
7
}

2. 实际案例：自己写的 Plugin#

案例1：生成文件列表插件#

自动生成项目中所有打包文件的列表。

1
class FileListPlugin {
2
  constructor(options) {
3
    // 接收配置参数
4
    this.options = options || {}
5
    this.filename = this.options.filename || 'filelist.md'
6
  }
7

8
  apply(compiler) {
9
    // 在emit阶段（生成资源到output目录之前）
10
    compiler.hooks.emit.tapAsync(
11
      'FileListPlugin',
12
      (compilation, callback) => {
13
        // 获取所有生成的文件
14
        let filelist = '# File List\n\n'
15

16
        for (let filename in compilation.assets) {
17
          filelist += `- ${filename}\n`
18
        }
19

20
        // 将文件列表作为新资源添加到输出
21
        compilation.assets[this.filename] = {
22
          source: () => filelist,
23
          size: () => filelist.length
24
        }
25

26
        callback()
27
      }
28
    )
29
  }
30
}
31

32
module.exports = FileListPlugin

案例2：打包进度插件#

在控制台输出构建进度和时间统计。

1
class BuildProgressPlugin {
2
  apply(compiler) {
3
    let startTime
4

5
    // 编译开始
6
    compiler.hooks.compile.tap('BuildProgressPlugin', () => {
7
      startTime = Date.now()
8
      console.log('🚀 开始编译...')
9
    })
10

11
    // 编译完成
12
    compiler.hooks.done.tap('BuildProgressPlugin', (stats) => {
13
      const duration = Date.now() - startTime
14

15
      if (stats.hasErrors()) {
16
        console.log('❌ 编译失败')
17
      } else {
18
        console.log(`✅ 编译成功！耗时: ${duration}ms`)
19
      }
20
    })
21
  }
22
}
23

24
module.exports = BuildProgressPlugin

案例3：清理注释插件#

自动清理生成的 JS 文件中的注释。

1
class RemoveCommentsPlugin {
2
  apply(compiler) {
3
    compiler.hooks.emit.tap('RemoveCommentsPlugin', (compilation) => {
4
      // 遍历所有生成的资源
5
      for (let filename in compilation.assets) {
6
        // 只处理JS文件
7
        if (filename.endsWith('.js')) {
8
          let content = compilation.assets[filename].source()
9

10
          // 移除单行注释
11
          content = content.replace(/\/\/.*/g, '')
12
          // 移除多行注释
13
          content = content.replace(/\/\*[\s\S]*?\*\//g, '')
14

15
          // 更新资源
16
          compilation.assets[filename] = {
17
            source: () => content,
18
            size: () => content.length
19
          }
20
        }
21
      }
22
    })
23
  }
24
}
25

26
module.exports = RemoveCommentsPlugin

案例4：上传到 CDN 插件#

构建完成后自动将资源上传到 CDN。

1
class UploadCDNPlugin {
2
  constructor(options) {
3
    this.cdnUrl = options.cdnUrl
4
    this.uploadFn = options.uploadFn
5
  }
6

7
  apply(compiler) {
8
    // 在资源生成后上传
9
    compiler.hooks.afterEmit.tapAsync(
10
      'UploadCDNPlugin',
11
      async (compilation, callback) => {
12
        const assets = compilation.assets
13

14
        console.log('📤 开始上传到CDN...')
15

16
        try {
17
          for (let filename in assets) {
18
            const filePath = assets[filename].existsAt
19
            await this.uploadFn(filePath, this.cdnUrl)
20
            console.log(`✅ ${filename} 上传成功`)
21
          }
22
          callback()
23
        } catch (error) {
24
          console.error('❌ 上传失败:', error)
25
          callback(error)
26
        }
27
      }
28
    )
29
  }
30
}
31

32
module.exports = UploadCDNPlugin

3. Webpack 生命周期钩子（Hooks）#

Webpack 使用 Tapable 库来管理钩子系统，主要有两个核心对象：

3.1 Compiler 钩子（全局级别）#

Compiler 对象代表了完整的 webpack 环境配置，在 webpack 启动时创建，全局唯一。

1
// Compiler 主要钩子
2
compiler.hooks = {
3
  // 1. 环境准备阶段
4
  environment: SyncHook,           // 环境准备好
5
  afterEnvironment: SyncHook,      // 环境准备完成
6

7
  // 2. 入口配置阶段
8
  entryOption: SyncBailHook,       // entry配置处理
9
  afterPlugins: SyncHook,          // 插件加载完成
10
  afterResolvers: SyncHook,        // 解析器设置完成
11

12
  // 3. 编译阶段
13
  beforeRun: AsyncSeriesHook,      // 编译器开始运行前
14
  run: AsyncSeriesHook,            // 编译器开始运行
15
  watchRun: AsyncSeriesHook,       // watch模式下编译开始
16

17
  beforeCompile: AsyncSeriesHook,  // 编译参数创建后
18
  compile: SyncHook,               // 开始编译
19
  thisCompilation: SyncHook,       // 触发compilation事件前
20
  compilation: SyncHook,           // compilation对象创建
21
  make: AsyncParallelHook,         // 完成一次编译前
22

23
  // 4. 输出阶段
24
  shouldEmit: SyncBailHook,        // 是否应该生成资源
25
  emit: AsyncSeriesHook,           // 生成资源到output目录前
26
  afterEmit: AsyncSeriesHook,      // 生成资源到output目录后
27
  assetEmitted: AsyncSeriesHook,   // 资源已生成
28

29
  // 5. 完成阶段
30
  done: AsyncSeriesHook,           // 编译完成
31
  failed: SyncHook,                // 编译失败
32

33
  // 6. 无效阶段
34
  invalid: SyncHook,               // watch模式文件变化
35
  watchClose: SyncHook             // watch模式停止
36
}

3.2 Compilation 钩子（编译级别）#

Compilation 对象代表一次资源版本构建，每次文件变化都会创建新的 Compilation。

1
// Compilation 主要钩子
2
compilation.hooks = {
3
  // 1. 构建阶段
4
  buildModule: SyncHook,              // 构建模块前
5
  rebuildModule: SyncHook,            // 重新构建模块
6
  failedModule: SyncHook,             // 模块构建失败
7
  succeedModule: SyncHook,            // 模块构建成功
8
  finishModules: AsyncSeriesHook,     // 所有模块构建完成
9

10
  // 2. 模块处理阶段
11
  seal: SyncHook,                     // 开始封装
12
  beforeChunks: SyncHook,             // 生成chunks前
13
  afterChunks: SyncHook,              // 生成chunks后
14

15
  // 3. 优化阶段
16
  optimize: SyncHook,                 // 优化开始
17
  optimizeModules: SyncBailHook,      // 优化模块
18
  optimizeChunks: SyncBailHook,       // 优化chunks
19
  optimizeTree: AsyncSeriesHook,      // 优化依赖树
20
  optimizeChunkModules: SyncBailHook, // 优化chunk中的模块
21

22
  // 模块优化
23
  optimizeModuleIds: SyncHook,        // 优化模块ID
24
  afterOptimizeModuleIds: SyncHook,   // 模块ID优化完成
25

26
  // Chunk优化
27
  optimizeChunkIds: SyncHook,         // 优化chunkID
28
  afterOptimizeChunkIds: SyncHook,    // chunkID优化完成
29

30
  // 4. 资源生成阶段
31
  beforeModuleAssets: SyncHook,       // 创建模块资源前
32
  moduleAsset: SyncHook,              // 模块资源生成
33
  chunkAsset: SyncHook,               // chunk资源生成
34

35
  // 5. 资源优化阶段
36
  processAssets: AsyncSeriesHook,     // 处理资源（重要！）
37
  afterProcessAssets: SyncHook,       // 资源处理完成
38

39
  optimizeAssets: AsyncSeriesHook,    // 优化资源
40
  afterOptimizeAssets: SyncHook,      // 资源优化完成
41

42
  // 6. 生成hash
43
  beforeHash: SyncHook,               // 生成hash前
44
  afterHash: SyncHook,                // 生成hash后
45

46
  // 7. 记录
47
  record: SyncHook,                   // 存储记录
48

49
  // 8. 完成
50
  beforeModuleIds: SyncHook,          // 模块ID分配前
51
  moduleIds: SyncHook,                // 模块ID分配
52

53
  needAdditionalPass: SyncBailHook,   // 是否需要额外的pass
54

55
  succeedModule: SyncHook,            // 模块成功
56
  stillValidModule: SyncHook,         // 模块仍然有效
57

58
  // stats相关
59
  statsPreset: HookMap,               // stats预设
60
  statsNormalize: SyncHook,           // stats标准化
61
  statsFactory: SyncHook,             // stats工厂
62
  statsPrinter: SyncHook              // stats打印
63
}

4. 钩子类型说明#

4.1 SyncHook - 同步钩子#

1
compiler.hooks.compile.tap('MyPlugin', () => {
2
  console.log('同步执行')
3
})

4.2 SyncBailHook - 同步熔断钩子#

返回非 undefined 值会停止后续钩子执行。

1
compiler.hooks.shouldEmit.tap('MyPlugin', (compilation) => {
2
  return false // 阻止生成资源
3
})

4.3 AsyncSeriesHook - 异步串行钩子#

方式1: callback

1
compiler.hooks.emit.tapAsync('MyPlugin', (compilation, callback) => {
2
  setTimeout(() => {
3
    console.log('异步操作')
4
    callback()
5
  }, 1000)
6
})

方式2: promise

1
compiler.hooks.emit.tapPromise('MyPlugin', (compilation) => {
2
  return new Promise((resolve) => {
3
    setTimeout(() => {
4
      console.log('异步操作')
5
      resolve()
6
    }, 1000)
7
  })
8
})

方式3: async/await

1
compiler.hooks.emit.tapPromise('MyPlugin', async (compilation) => {
2
  await someAsyncOperation()
3
  console.log('异步操作完成')
4
})

4.4 AsyncParallelHook - 异步并行钩子#

1
compiler.hooks.make.tapAsync('MyPlugin', (compilation, callback) => {
2
  // 所有注册的回调会并行执行
3
  callback()
4
})

5. 完整实战案例：自动生成版本信息插件#

1
const fs = require('fs')
2
const path = require('path')
3

4
class VersionPlugin {
5
  constructor(options = {}) {
6
    this.options = {
7
      filename: 'version.json',
8
      includeHash: true,
9
      includeTime: true,
10
      ...options
11
    }
12
  }
13

14
  apply(compiler) {
15
    const pluginName = 'VersionPlugin'
16

17
    // 1. 编译开始时记录时间
18
    let startTime
19
    compiler.hooks.compile.tap(pluginName, () => {
20
      startTime = Date.now()
21
      console.log('📦 开始构建...')
22
    })
23

24
    // 2. 在生成资源前创建版本文件
25
    compiler.hooks.emit.tapAsync(pluginName, (compilation, callback) => {
26
      const stats = compilation.getStats().toJson()
27

28
      const versionInfo = {
29
        version: this.getVersion(),
30
        buildTime: this.options.includeTime ? new Date().toISOString() : undefined,
31
        hash: this.options.includeHash ? stats.hash : undefined,
32
        duration: Date.now() - startTime,
33
        assets: Object.keys(compilation.assets).map(name => ({
34
          name,
35
          size: compilation.assets[name].size()
36
        }))
37
      }
38

39
      const content = JSON.stringify(versionInfo, null, 2)
40

41
      // 添加到输出资源
42
      compilation.assets[this.options.filename] = {
43
        source: () => content,
44
        size: () => content.length
45
      }
46

47
      console.log(`✅ 版本信息已生成: ${this.options.filename}`)
48
      callback()
49
    })
50

51
    // 3. 编译完成后的处理
52
    compiler.hooks.done.tap(pluginName, (stats) => {
53
      if (stats.hasErrors()) {
54
        console.log('❌ 构建失败')
55
        return
56
      }
57

58
      const duration = Date.now() - startTime
59
      console.log(`✅ 构建成功！耗时: ${duration}ms`)
60

61
      // 输出统计信息
62
      const info = stats.toJson()
63
      console.log(`📊 资源数量: ${Object.keys(info.assets).length}`)
64
      console.log(`📦 总大小: ${this.formatSize(info.assets.reduce((sum, asset) => sum + asset.size, 0))}`)
65
    })
66

67
    // 4. 监听文件变化
68
    compiler.hooks.watchRun.tap(pluginName, (compiler) => {
69
      const changedFiles = compiler.modifiedFiles
70
      if (changedFiles && changedFiles.size > 0) {
71
        console.log('🔄 检测到文件变化:', Array.from(changedFiles).join(', '))
72
      }
73
    })
74
  }
75

76
  // 读取package.json的版本号
77
  getVersion() {
78
    try {
79
      const pkgPath = path.resolve(process.cwd(), 'package.json')
80
      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'))
81
      return pkg.version || '0.0.0'
82
    } catch (e) {
83
      return '0.0.0'
84
    }
85
  }
86

87
  // 格式化文件大小
88
  formatSize(bytes) {
89
    if (bytes < 1024) return bytes + ' B'
90
    if (bytes < 1024 * 1024) return (bytes / 1024).toFixed(2) + ' KB'
91
    return (bytes / (1024 * 1024)).toFixed(2) + ' MB'
92
  }
93
}
94

95
module.exports = VersionPlugin

使用这个插件#

1
const VersionPlugin = require('./plugins/VersionPlugin')
2

3
module.exports = {
4
  plugins: [
5
    new VersionPlugin({
6
      filename: 'build-info.json',
7
      includeHash: true,
8
      includeTime: true
9
    })
10
  ]
11
}

生成的 build-info.json#

1
{
2
  "version": "1.0.0",
3
  "buildTime": "2025-01-04T10:30:00.000Z",
4
  "hash": "a1b2c3d4e5f6",
5
  "duration": 2345,
6
  "assets": [
7
    {
8
      "name": "main.a1b2c3.js",
9
      "size": 245678
10
    },
11
    {
12
      "name": "main.a1b2c3.css",
13
      "size": 12345
14
    }
15
  ]
16
}

6. 常用生命周期钩子速查表#

📌 最常用的钩子#

1
// 1. 编译开始
2
compiler.hooks.compile.tap()              // 同步
3

4
// 2. 生成资源前（修改输出内容）
5
compiler.hooks.emit.tapAsync()            // 异步
6

7
// 3. 生成资源后（上传CDN等）
8
compiler.hooks.afterEmit.tapAsync()       // 异步
9

10
// 4. 编译完成
11
compiler.hooks.done.tap()                 // 同步
12

13
// 5. 优化资源（压缩、处理等）
14
compilation.hooks.processAssets.tap()     // 同步
15

16
// 6. 优化chunks
17
compilation.hooks.optimizeChunks.tap()    // 同步
18

19
// 7. 模块构建完成
20
compilation.hooks.finishModules.tap()     // 同步

7. 调试技巧#

1
class DebugPlugin {
2
  apply(compiler) {
3
    // 打印所有可用的钩子
4
    console.log('Compiler hooks:', Object.keys(compiler.hooks))
5

6
    // 监听所有compilation钩子
7
    compiler.hooks.compilation.tap('DebugPlugin', (compilation) => {
8
      console.log('Compilation hooks:', Object.keys(compilation.hooks))
9

10
      // 打印每个阶段
11
      compilation.hooks.seal.tap('DebugPlugin', () => {
12
        console.log('📍 Seal stage')
13
      })
14

15
      compilation.hooks.optimize.tap('DebugPlugin', () => {
16
        console.log('📍 Optimize stage')
17
      })
18
    })
19
  }
20
}

总结#

Plugin 开发核心要点#

✅ Plugin必须是一个类或对象，包含 apply 方法
✅ 通过 compiler/compilation 的 hooks 注册回调
✅ 了解钩子的类型（同步/异步）和执行时机
✅ 使用 tap/tapAsync/tapPromise 注册回调
✅ 异步钩子必须调用 callback 或返回 Promise

最常用的生命周期#

compile - 编译开始
emit - 生成资源前（最常用）
done - 编译完成
compilation.processAssets - 处理资源（Webpack 5推荐）