4、Webpack Plugin实战：HtmlWebpackPlugin、MiniCssExtractPlugin、DefinePlugin、CleanWebpackPlugin，自定义Plugin开发

Plugin 是 Webpack 的灵魂。Loader 只管文件转换，Plugin 却能触及构建的每个环节——从资源生成到环境注入，从清理到优化。我刚开始用 Webpack 时，总觉得 Plugin 是个黑盒，直到自己动手写了一个，才明白它的设计有多巧妙。

这一章，我们挑几个最常用的 Plugin 拆开来看。不光讲用法，还会聊聊它们背后的原理，以及我在项目中踩过的坑。

4.1 HtmlWebpackPlugin：自动生成 HTML

没有它的时候，你得手动维护一个 index.html，每次打包后手动改 script 标签的 hash。说实话，这活干一次就想吐。

// webpack.config.js
const HtmlWebpackPlugin = require('html-webpack-plugin');

module.exports = {
  plugins: [
    new HtmlWebpackPlugin({
      template: './src/index.html',  // 模板路径
      filename: 'index.html',        // 输出文件名
      title: '我的应用',
      inject: true                   // 自动注入所有打包资源
    })
  ]
};

它的核心能力就两个：自动注入 和 模板渲染。你想想看，每次构建生成的 chunk 文件名都带 hash，手动维护根本不可能。HtmlWebpackPlugin 会自动扫描所有输出的 JS/CSS，按顺序插入到 HTML 中。

4.2 MiniCssExtractPlugin：CSS 文件分离

默认情况下，Webpack 会把 CSS 打包进 JS 文件，通过 style-loader 注入到页面。开发时没问题，但生产环境这么做有两个坏处：

• CSS 和 JS 耦合，无法并行加载
• CSS 体积大时，会阻塞 JS 执行

MiniCssExtractPlugin 的作用就是把 CSS 提取成独立的文件。说白了，就是让浏览器能同时下载 JS 和 CSS，提升加载速度。

const MiniCssExtractPlugin = require('mini-css-extract-plugin');

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          MiniCssExtractPlugin.loader,  // 替代 style-loader
          'css-loader'
        ]
      }
    ]
  },
  plugins: [
    new MiniCssExtractPlugin({
      filename: 'css/[name].[contenthash:8].css',
      chunkFilename: 'css/[id].[contenthash:8].css'
    })
  ]
};

这里有个细节要注意：开发环境建议用 style-loader，因为它支持 HMR（热模块替换）。MiniCssExtractPlugin 的 loader 不支持 HMR，每次改 CSS 都会触发全量刷新。我个人习惯在 webpack.common.js 里配置两套规则，通过环境变量切换。

4.3 DefinePlugin：注入全局常量

这个 Plugin 看起来简单，但用不好会出大问题。它的作用是在编译时替换代码中的全局变量。最常见的场景就是区分开发环境和生产环境。

const webpack = require('webpack');

module.exports = {
  plugins: [
    new webpack.DefinePlugin({
      'process.env.NODE_ENV': JSON.stringify('production'),
      'API_BASE_URL': JSON.stringify('https://api.example.com'),
      'APP_VERSION': JSON.stringify('1.0.0')
    })
  ]
};

你可能会问：为什么不直接在代码里写死？因为不同环境需要不同的配置。比如开发环境用本地 API，生产环境用线上 API。DefinePlugin 会在编译时直接把变量替换成对应的值，不会保留任何运行时开销。

嗯，这里要注意：值必须用 JSON.stringify 包裹。我见过有人直接写 'process.env.NODE_ENV': 'production'，结果代码里变成了 if ('production' === 'production')，永远为 true。因为 DefinePlugin 做的是文本替换，不是变量赋值。

4.4 CleanWebpackPlugin：自动清理输出目录

每次打包前手动删除 dist 目录？太原始了。CleanWebpackPlugin 会在每次构建前清空输出目录，保证产物是最新的。

const { CleanWebpackPlugin } = require('clean-webpack-plugin');

module.exports = {
  plugins: [
    new CleanWebpackPlugin({
      cleanOnceBeforeBuildPatterns: ['**/*', '!static-files/**'],
      dry: false,  // 设为 true 只显示要删除的文件，不实际删除
      verbose: true
    })
  ]
};

它的原理很简单：读取 output.path 配置，删除该目录下的所有文件。但有个坑——如果你在输出目录外有文件需要保留，比如一些静态资源是手动放进去的，可以用 cleanOnceBeforeBuildPatterns 配置排除规则。

4.5 自定义 Plugin 开发

讲完了常用 Plugin，我们来聊聊怎么自己写一个。说实话，自定义 Plugin 并没有想象中那么难。它的本质就是一个 带有 apply 方法的类。

// 一个简单的自定义 Plugin：在构建完成后输出文件列表
class FileListPlugin {
  constructor(options) {
    this.options = options || {};
    this.filename = this.options.filename || 'filelist.txt';
  }

  apply(compiler) {
    // compiler 代表完整的 Webpack 配置
    compiler.hooks.emit.tapAsync('FileListPlugin', (compilation, callback) => {
      // compilation 代表本次构建的上下文
      const fileList = [];

      for (const filename in compilation.assets) {
        fileList.push(filename);
      }

      const content = fileList.join('\n');
      compilation.assets[this.filename] = {
        source: () => content,
        size: () => content.length
      };

      callback();
    });
  }
}

module.exports = FileListPlugin;

这个 Plugin 会在每次构建完成后，在输出目录生成一个 filelist.txt，里面列出了所有产出的文件名。虽然简单，但它展示了自定义 Plugin 的核心流程：

1. 定义类，构造函数接收用户传入的 options
2. 实现 apply 方法，接收 compiler 对象
3. 选择合适的 hooks，挂载回调函数
4. 操作 compilation，修改或添加资源

Webpack 的 Plugin 系统基于 Tapable 事件流框架。compiler 和 compilation 上挂载了大量 hooks，每个 hook 对应构建流程中的一个阶段。你想想看，从开始编译到输出文件，中间有几十个钩子可以介入。

我在项目中写过最实用的一个自定义 Plugin，是用来做 构建版本标记 的。每次构建时，自动读取 Git 的 commit hash 和构建时间，注入到打包后的 JS 中，方便线上排查问题。

class VersionPlugin {
  apply(compiler) {
    compiler.hooks.emit.tapAsync('VersionPlugin', (compilation, callback) => {
      const version = {
        buildTime: new Date().toISOString(),
        commitHash: require('child_process')
          .execSync('git rev-parse HEAD')
          .toString()
          .trim()
      };

      // 在所有 JS 文件末尾追加版本信息
      for (const filename in compilation.assets) {
        if (filename.endsWith('.js')) {
          const source = compilation.assets[filename].source();
          const newSource = source + `\n/* Version: ${JSON.stringify(version)} */`;
          compilation.assets[filename] = {
            source: () => newSource,
            size: () => newSource.length
          };
        }
      }

      callback();
    });
  }
}

4.6 本章知识图谱

下面这张图梳理了 Plugin 的核心工作流程，以及本章涉及的几个 Plugin 在流程中的位置：

从这张图可以看得很清楚：每个 Plugin 只关注自己负责的 Hook。DefinePlugin 在编译阶段替换变量，CleanWebpackPlugin 在输出前清理目录，HtmlWebpackPlugin 和 MiniCssExtractPlugin 在生成资源阶段工作，自定义 Plugin 则可以挂载到任意位置。

理解了这个流程，你就能根据需求选择合适的 Hook 来开发自己的 Plugin。说白了，Plugin 开发就是 在正确的时间点做正确的事。