实战：开发 Webpack 插件及最佳实践

2025年11月17日

通过实战案例学习如何开发 Webpack 插件，并掌握开发过程中的最佳实践，是提升插件开发能力的最佳途径。本文将通过三个完整的实战案例，带你从零开发实用的插件。

开发环境准备

项目结构

my-webpack-plugin/
├── src/
│   ├── FileListPlugin.js
│   ├── BuildProgressPlugin.js
│   └── AssetSizePlugin.js
├── test/
│   ├── webpack.config.js
│   └── src/
│       └── index.js
├── package.json
└── README.md

初始化项目

mkdir my-webpack-plugin
cd my-webpack-plugin
npm init -y
npm install webpack webpack-cli --save-dev

本地测试插件

有两种方式在本地测试插件：

方法 1：直接引用本地文件

// webpack.config.js
const path = require('path');
const MyPlugin = require('./src/MyPlugin');

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

方法 2：使用 npm link

# 在插件项目目录
npm link

# 在测试项目目录
npm link my-webpack-plugin

实战案例 1：文件清单插件

需求分析

创建一个插件，在每次构建后生成一个 Markdown 格式的文件清单，包含：

所有生成的文件列表
每个文件的大小
构建时间戳

完整实现

使用方式

const FileListPlugin = require('./src/FileListPlugin');

module.exports = {
  // ...
  plugins: [
    new FileListPlugin({
      filename: 'build-manifest.md'
    })
  ]
};

增强版本：支持过滤和排序

使用示例：

实战案例 2：构建进度插件

需求分析

创建一个插件，实时显示构建进度，包括：

构建开始和结束提示
模块构建进度
构建耗时统计
错误和警告提示

完整实现

使用方式

plugins: [
  new BuildProgressPlugin({
    showModuleProgress: true,
    moduleProgressInterval: 50  // 每 50 个模块显示一次进度
  })
]

实战案例 3：资源大小分析插件

需求分析

创建一个插件，分析构建产物的大小，并提供警告和建议：

检测超过指定大小的文件
生成大小分析报告
提供优化建议

完整实现

加载中...

实战：开发 Webpack 插件及最佳实践 | underflowed

实战：开发 Webpack 插件及最佳实践

2025年11月17日

开发环境准备

项目结构

my-webpack-plugin/
├── src/
│   ├── FileListPlugin.js
│   ├── BuildProgressPlugin.js
│   └── AssetSizePlugin.js
├── test/
│   ├── webpack.config.js
│   └── src/
│       └── index.js
├── package.json
└── README.md

初始化项目

mkdir my-webpack-plugin
cd my-webpack-plugin
npm init -y
npm install webpack webpack-cli --save-dev

本地测试插件

有两种方式在本地测试插件：

方法 1：直接引用本地文件

// webpack.config.js
const path = require('path');
const MyPlugin = require('./src/MyPlugin');

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

方法 2：使用 npm link

# 在插件项目目录
npm link

# 在测试项目目录
npm link my-webpack-plugin

实战案例 1：文件清单插件

需求分析

创建一个插件，在每次构建后生成一个 Markdown 格式的文件清单，包含：

所有生成的文件列表
每个文件的大小
构建时间戳

完整实现

// src/FileListPlugin.js
class FileListPlugin {
  constructor(options = {}) {
    // 配置选项
    this.filename = options.filename || 'filelist.md';
    this.outputPath = options.outputPath || '';
  }

  apply(compiler) {
    const pluginName = 'FileListPlugin';

    // 在资源输出前生成文件清单
    compiler.hooks.emit.tapAsync(pluginName, (compilation, callback) => {
      // 获取所有资源文件
      const assets = compilation.assets;
      const files = Object.keys(assets);

      // 生成文件列表
      const fileList = files
        .map(filename => {
          const size = assets[filename].size();
          const sizeKB = (size / 1024).toFixed(2);
          return `- ${filename} (${sizeKB} KB)`;
        })
        .join('\n');

      // 生成 Markdown 内容
      const content = `# 构建文件清单\n\n` +
        `**构建时间**: ${new Date().toLocaleString()}\n\n` +
        `**文件总数**: ${files.length}\n\n` +
        `## 文件列表\n\n${fileList}`;

      // 添加到构建资源
      compilation.assets[this.filename] = {
        source: () => content,
        size: () => content.length
      };

      callback();
    });
  }
}

module.exports = FileListPlugin;

使用方式

const FileListPlugin = require('./src/FileListPlugin');

module.exports = {
  // ...
  plugins: [
    new FileListPlugin({
      filename: 'build-manifest.md'
    })
  ]
};

增强版本：支持过滤和排序

class FileListPlugin {
  constructor(options = {}) {
    this.filename = options.filename || 'filelist.md';
    this.filter = options.filter || (() => true);  // 过滤函数
    this.sort = options.sort || 'name';  // 排序方式: 'name' | 'size'
  }

  apply(compiler) {
    compiler.hooks.emit.tapAsync('FileListPlugin', (compilation, callback) => {
      const assets = compilation.assets;
      
      // 获取并处理文件列表
      let files = Object.keys(assets)
        .filter(this.filter)  // 应用过滤
        .map(filename => ({
          name: filename,
          size: assets[filename].size()
        }));

      // 排序
      if (this.sort === 'size') {
        files.sort((a, b) => b.size - a.size);
      } else {
        files.sort((a, b) => a.name.localeCompare(b.name));
      }

      // 计算总大小
      const totalSize = files.reduce((sum, file) => sum + file.size, 0);

      // 生成文件列表
      const fileList = files
        .map(file => {
          const sizeKB = (file.size / 1024).toFixed(2);
          const percent = ((file.size / totalSize) * 100).toFixed(2);
          return `- ${file.name} - ${sizeKB} KB (${percent}%)`;
        })
        .join('\n');

      const content = `# 构建文件清单\n\n` +
        `**构建时间**: ${new Date().toLocaleString()}\n` +
        `**文件总数**: ${files.length}\n` +
        `**总大小**: ${(totalSize / 1024).toFixed(2)} KB\n\n` +
        `## 文件列表 (按${this.sort === 'size' ? '大小' : '名称'}排序)\n\n` +
        `${fileList}`;

      compilation.assets[this.filename] = {
        source: () => content,
        size: () => content.length
      };

      callback();
    });
  }
}

使用示例：

plugins: [
  new FileListPlugin({
    filename: 'manifest.md',
    filter: (filename) => !filename.endsWith('.map'),  // 排除 map 文件
    sort: 'size'  // 按大小排序
  })
]

实战案例 2：构建进度插件

需求分析

创建一个插件，实时显示构建进度，包括：

构建开始和结束提示
模块构建进度
构建耗时统计
错误和警告提示

完整实现

// src/BuildProgressPlugin.js
class BuildProgressPlugin {
  constructor(options = {}) {
    this.showModuleProgress = options.showModuleProgress !== false;
    this.moduleProgressInterval = options.moduleProgressInterval || 100;
  }

  apply(compiler) {
    const startTime = {};
    let moduleCount = 0;

    // 编译开始
    compiler.hooks.compile.tap('BuildProgressPlugin', () => {
      startTime.compile = Date.now();
      moduleCount = 0;
      console.log('\n🚀 开始构建...');
    });

    // 获取 compilation
    compiler.hooks.compilation.tap('BuildProgressPlugin', (compilation) => {
      // 模块构建开始
      compilation.hooks.buildModule.tap('BuildProgressPlugin', (module) => {
        moduleCount++;
        
        if (this.showModuleProgress && 
            moduleCount % this.moduleProgressInterval === 0) {
          process.stdout.write(`\r📦 正在构建模块: ${moduleCount} 个`);
        }
      });

      // 所有模块构建完成
      compilation.hooks.finishModules.tap('BuildProgressPlugin', (modules) => {
        const duration = ((Date.now() - startTime.compile) / 1000).toFixed(2);
        console.log(`\n✅ 模块构建完成: 共 ${modules.size} 个模块 (耗时 ${duration}s)`);
      });

      // 优化阶段
      compilation.hooks.optimize.tap('BuildProgressPlugin', () => {
        console.log('🔧 开始优化...');
      });

      // chunk 优化完成
      compilation.hooks.afterOptimizeChunks.tap('BuildProgressPlugin', (chunks) => {
        console.log(`📊 生成了 ${chunks.size} 个 chunk`);
      });
    });

    // 资源输出前
    compiler.hooks.emit.tapAsync('BuildProgressPlugin', (compilation, callback) => {
      const assetCount = Object.keys(compilation.assets).length;
      console.log(`📝 准备输出 ${assetCount} 个文件...`);
      callback();
    });

    // 构建完成
    compiler.hooks.done.tap('BuildProgressPlugin', (stats) => {
      const totalTime = ((Date.now() - startTime.compile) / 1000).toFixed(2);

      console.log('\n' + '='.repeat(50));
      
      if (stats.hasErrors()) {
        const errors = stats.compilation.errors.length;
        console.log(`❌ 构建失败: ${errors} 个错误 (耗时 ${totalTime}s)`);
        this.printErrors(stats.compilation.errors);
      } else if (stats.hasWarnings()) {
        const warnings = stats.compilation.warnings.length;
        console.log(`⚠️  构建完成: ${warnings} 个警告 (耗时 ${totalTime}s)`);
        this.printWarnings(stats.compilation.warnings);
      } else {
        console.log(`✨ 构建成功! (耗时 ${totalTime}s)`);
      }
      
      console.log('='.repeat(50) + '\n');
    });

    // 构建失败
    compiler.hooks.failed.tap('BuildProgressPlugin', (error) => {
      console.error('\n💥 构建失败:', error.message);
    });
  }

  printErrors(errors) {
    console.log('\n错误详情:');
    errors.slice(0, 3).forEach((error, index) => {
      console.log(`\n${index + 1}. ${error.message}`);
    });
    if (errors.length > 3) {
      console.log(`\n... 还有 ${errors.length - 3} 个错误`);
    }
  }

  printWarnings(warnings) {
    console.log('\n警告详情:');
    warnings.slice(0, 3).forEach((warning, index) => {
      console.log(`\n${index + 1}. ${warning.message}`);
    });
    if (warnings.length > 3) {
      console.log(`\n... 还有 ${warnings.length - 3} 个警告`);
    }
  }
}

module.exports = BuildProgressPlugin;

使用方式

plugins: [
  new BuildProgressPlugin({
    showModuleProgress: true,
    moduleProgressInterval: 50  // 每 50 个模块显示一次进度
  })
]

实战案例 3：资源大小分析插件

需求分析

创建一个插件，分析构建产物的大小，并提供警告和建议：

检测超过指定大小的文件
生成大小分析报告
提供优化建议

完整实现

// src/AssetSizePlugin.js
const chalk = require('chalk');  // 需要安装: npm install chalk

class AssetSizePlugin {
  constructor(options = {}) {
    this.maxSize = options.maxSize || 244 * 1024;  // 默认 244KB
    this.maxTotalSize = options.maxTotalSize || 5 * 1024 * 1024;  // 默认 5MB
    this.showAllAssets = options.showAllAssets !== false;
    this.generateReport = options.generateReport !== false;
  }

  apply(compiler) {
    compiler.hooks.emit.tapAsync('AssetSizePlugin', (compilation, callback) => {
      const assets = compilation.assets;
      const warnings = [];
      const assetInfo = [];

      let totalSize = 0;

      // 分析每个资源
      Object.keys(assets).forEach(filename => {
        const asset = assets[filename];
        const size = asset.size();
        totalSize += size;

        assetInfo.push({
          name: filename,
          size: size,
          sizeKB: (size / 1024).toFixed(2),
          sizeMB: (size / 1024 / 1024).toFixed(2)
        });

        // 检查单个文件大小
        if (size > this.maxSize) {
          const sizeKB = (size / 1024).toFixed(2);
          const maxSizeKB = (this.maxSize / 1024).toFixed(2);
          warnings.push(
            `文件 "${filename}" 过大: ${sizeKB} KB (建议不超过 ${maxSizeKB} KB)`
          );
        }
      });

      // 检查总大小
      if (totalSize > this.maxTotalSize) {
        const totalMB = (totalSize / 1024 / 1024).toFixed(2);
        const maxTotalMB = (this.maxTotalSize / 1024 / 1024).toFixed(2);
        warnings.push(
          `总文件大小过大: ${totalMB} MB (建议不超过 ${maxTotalMB} MB)`
        );
      }

      // 输出报告
      this.printReport(assetInfo, totalSize, warnings);

      // 生成报告文件
      if (this.generateReport) {
        const reportContent = this.generateReportContent(assetInfo, totalSize, warnings);
        compilation.assets['size-report.md'] = {
          source: () => reportContent,
          size: () => reportContent.length
        };
      }

      // 将警告添加到 compilation
      warnings.forEach(warning => {
        compilation.warnings.push(new Error(warning));
      });

      callback();
    });
  }

  printReport(assetInfo, totalSize, warnings) {
    console.log('\n' + chalk.bold.cyan('📊 资源大小分析'));
    console.log('='.repeat(70));

    // 按大小排序
    const sortedAssets = assetInfo.sort((a, b) => b.size - a.size);

    if (this.showAllAssets) {
      console.log('\n' + chalk.bold('所有资源:'));
      sortedAssets.forEach(asset => {
        const percent = ((asset.size / totalSize) * 100).toFixed(2);
        const sizeStr = asset.size > 1024 * 1024 
          ? `${asset.sizeMB} MB`
          : `${asset.sizeKB} KB`;
        
        console.log(
          `  ${chalk.gray(asset.name)} - ` +
          `${chalk.yellow(sizeStr)} ` +
          `${chalk.gray(`(${percent}%)`)}`
        );
      });
    } else {
      // 只显示前 10 大文件
      console.log('\n' + chalk.bold('最大的 10 个文件:'));
      sortedAssets.slice(0, 10).forEach((asset

// src/BuildProgressPlugin.js
class BuildProgressPlugin {
  constructor(options = {}) {
    this.showModuleProgress = options.showModuleProgress !== false;
    this.moduleProgressInterval = options.moduleProgressInterval || 100;
  }

  apply(compiler) {
    const startTime = {};
    let moduleCount = 0;

    // 编译开始
    compiler.hooks.compile.tap('BuildProgressPlugin', () => {
      startTime.compile = Date.now();
      moduleCount = 0;
      console.log('\n🚀 开始构建...');
    });

    // 获取 compilation
    compiler.hooks.compilation.tap('BuildProgressPlugin', (compilation) => {
      // 模块构建开始
      compilation.hooks.buildModule.tap('BuildProgressPlugin', (module) => {
        moduleCount++;
        
        if (this.showModuleProgress && 
            moduleCount % this.moduleProgressInterval === 0) {
          process.stdout.write(`\r📦 正在构建模块: ${moduleCount} 个`);
        }
      });

      // 所有模块构建完成
      compilation.hooks.finishModules.tap('BuildProgressPlugin', (modules) => {
        const duration = ((Date.now() - startTime.compile) / 1000).toFixed(2);
        console.log(`\n✅ 模块构建完成: 共 ${modules.size} 个模块 (耗时 ${duration}s)`);
      });

      // 优化阶段
      compilation.hooks.optimize.tap('BuildProgressPlugin', () => {
        console.log('🔧 开始优化...');
      });

      // chunk 优化完成
      compilation.hooks.afterOptimizeChunks.tap('BuildProgressPlugin', (chunks) => {
        console.log(`📊 生成了 ${chunks.size} 个 chunk`);
      });
    });

    // 资源输出前
    compiler.hooks.emit.tapAsync('BuildProgressPlugin', (compilation, callback) => {
      const assetCount = Object.keys(compilation.assets).length;
      console.log(`📝 准备输出 ${assetCount} 个文件...`);
      callback();
    });

    // 构建完成
    compiler.hooks.done.tap('BuildProgressPlugin', (stats) => {
      const totalTime = ((Date.now() - startTime.compile) / 1000).toFixed(2);

      console.log('\n' + '='.repeat(50));
      
      if (stats.hasErrors()) {
        const errors = stats.compilation.errors.length;
        console.log(`❌ 构建失败: ${errors} 个错误 (耗时 ${totalTime}s)`);
        this.printErrors(stats.compilation.errors);
      } else if (stats.hasWarnings()) {
        const warnings = stats.compilation.warnings.length;
        console.log(`⚠️  构建完成: ${warnings} 个警告 (耗时 ${totalTime}s)`);
        this.printWarnings(stats.compilation.warnings);
      } else {
        console.log(`✨ 构建成功! (耗时 ${totalTime}s)`);
      }
      
      console.log('='.repeat(50) + '\n');
    });

    // 构建失败
    compiler.hooks.failed.tap('BuildProgressPlugin', (error) => {
      console.error('\n💥 构建失败:', error.message);
    });
  }

  printErrors(errors) {
    console.log('\n错误详情:');
    errors.slice(0, 3).forEach((error, index) => {
      console.log(`\n${index + 1}. ${error.message}`);
    });
    if (errors.length > 3) {
      console.log(`\n... 还有 ${errors.length - 3} 个错误`);
    }
  }

  printWarnings(warnings) {
    console.log('\n警告详情:');
    warnings.slice(0, 3).forEach((warning, index) => {
      console.log(`\n${index + 1}. ${warning.message}`);
    });
    if (warnings.length > 3) {
      console.log(`\n... 还有 ${warnings.length - 3} 个警告`);
    }
  }
}

module.exports = BuildProgressPlugin;

// src/AssetSizePlugin.js
const chalk = require('chalk');  // 需要安装: npm install chalk

class AssetSizePlugin {
  constructor(options = {}) {
    this.maxSize = options.maxSize || 244 * 1024;  // 默认 244KB
    this.maxTotalSize = options.maxTotalSize || 5 * 1024 * 1024;  // 默认 5MB
    this.showAllAssets = options.showAllAssets !== false;
    this.generateReport = options.generateReport !== false;
  }

  apply(compiler) {
    compiler.hooks.emit.tapAsync('AssetSizePlugin', (compilation, callback) => {
      const assets = compilation.assets;
      const warnings = [];
      const assetInfo = [];

      let totalSize = 0;

      // 分析每个资源
      Object.keys(assets).forEach(filename => {
        const asset = assets[filename];
        const size = asset.size();
        totalSize += size;

        assetInfo.push({
          name: filename,
          size: size,
          sizeKB: (size / 1024).toFixed(2),
          sizeMB: (size / 1024 / 1024).toFixed(2)
        });

        // 检查单个文件大小
        if (size > this.maxSize) {
          const sizeKB = (size / 1024).toFixed(2);
          const maxSizeKB = (this.maxSize / 1024).toFixed(2);
          warnings.push(
            `文件 "${filename}" 过大: ${sizeKB} KB (建议不超过 ${maxSizeKB} KB)`
          );
        }
      });

      // 检查总大小
      if (totalSize > this.maxTotalSize) {
        const totalMB = (totalSize / 1024 / 1024).toFixed(2);
        const maxTotalMB = (this.maxTotalSize / 1024 / 1024).toFixed(2);
        warnings.push(
          `总文件大小过大: ${totalMB} MB (建议不超过 ${maxTotalMB} MB)`
        );
      }

      // 输出报告
      this.printReport(assetInfo, totalSize, warnings);

      // 生成报告文件
      if (this.generateReport) {
        const reportContent = this.generateReportContent(assetInfo, totalSize, warnings);
        compilation.assets['size-report.md'] = {
          source: () => reportContent,
          size: () => reportContent.length
        };
      }

      // 将警告添加到 compilation
      warnings.forEach(warning => {
        compilation.warnings.push(new Error(warning));
      });

      callback();
    });
  }

  printReport(assetInfo, totalSize, warnings) {
    console.log('\n' + chalk.bold.cyan('📊 资源大小分析'));
    console.log('='.repeat(70));

    // 按大小排序
    const sortedAssets = assetInfo.sort((a, b) => b.size - a.size);

    if (this.showAllAssets) {
      console.log('\n' + chalk.bold('所有资源:'));
      sortedAssets.forEach(asset => {
        const percent = ((asset.size / totalSize) * 100).toFixed(2);
        const sizeStr = asset.size > 1024 * 1024 
          ? `${asset.sizeMB} MB`
          : `${asset.sizeKB} KB`;
        
        console.log(
          `  ${chalk.gray(asset.name)} - ` +
          `${chalk.yellow(sizeStr)} ` +
          `${chalk.gray(`(${percent}%)`)}`
        );
      });
    } else {
      // 只显示前 10 大文件
      console.log('\n' + chalk.bold('最大的 10 个文件:'));
      sortedAssets.slice(0, 10).forEach((asset