Vite & Webpack 插件/Loader 封装完全指南

工程化构建中，Vite 与 Webpack 的核心扩展性依赖 插件（Plugin） 和 Loader：

• Loader：专注「文件转换」，将非 JS/CSS 资源（如 SCSS、TS、图片）转为构建工具可识别的模块，仅在「模块解析阶段」工作；
• Plugin：专注「流程增强」，拦截构建全生命周期（如编译前、打包后），实现自定义功能（如文件压缩、资源注入、日志输出），能力覆盖 Loader 之外的所有场景。

本文从「核心概念→封装规范→实战案例→差异对比→避坑指南」全方位拆解，新手能快速上手封装，老手可落地复杂场景。

一、核心前置认知（先搞懂本质）

1. Vite vs Webpack 核心差异（影响封装逻辑）

维度	Webpack（老牌构建工具）	Vite（新一代构建工具）
底层原理	基于「打包器」：先递归解析所有模块→打包为单个/多个 bundle	基于「ESM 原生支持」：开发环境按需加载→生产环境用 Rollup 打包
插件机制	基于「Tapable 钩子」（事件流模式），拦截构建各阶段	基于「Rollup 插件规范+自定义钩子」，开发/生产环境钩子区分明确
Loader 机制	核心能力，需单独封装 Loader 处理文件转换	无独立 Loader 概念，文件转换通过「插件+预处理器」实现（兼容部分 Rollup 插件）
封装难度	中等（钩子多，配置繁琐）	简单（API 简洁，钩子少，贴近原生 ESM）
适用场景	复杂大型项目（多入口、多环境、复杂资源处理）	中小型项目、Vue/React 新项目（开发体验优先）

2. 插件 vs Loader 核心区别（避免混淆）

对比维度	Loader（文件转换器）	Plugin（流程增强器）
核心作用	转换非标准模块（如 SCSS→CSS、TS→JS）	增强构建流程（如资源注入、打包优化、日志打印）
执行时机	模块解析阶段（先执行 Loader 再执行 Plugin）	全生命周期（可在 Loader 前/后执行）
接收参数	输入「文件内容+SourceMap」，输出「转换后内容+SourceMap」	接收「构建工具配置」，无固定输入输出，通过钩子拦截流程
调用方式	在 module.rules 中配置，按顺序链式执行	在 plugins 数组中配置，按顺序执行
能力边界	仅处理文件转换，无流程控制能力	覆盖全构建流程，可修改配置、拦截资源、生成文件

二、Webpack 生态封装（Loader + Plugin）

Webpack 是目前最成熟的构建工具，Loader 和 Plugin 是其生态核心，需分别掌握封装规范。

（一）Webpack Loader 封装（文件转换）

1. Loader 核心规范（必须遵守）

• 单一职责：一个 Loader 只做一件事（如 SCSS 转 CSS 是一个 Loader，CSS 转 JS 是另一个 Loader），通过链式调用组合功能；
• 同步/异步：支持同步返回结果，也支持异步回调返回（处理耗时操作，如文件读取）；
• 参数接收 ：通过 this.query 或 loader-utils.getOptions(this) 获取配置参数；
• SourceMap ：支持生成 SourceMap（便于调试），通过 this.sourceMap 判断是否需要生成；
• 返回格式 ：同步返回 { code: 转换后内容, map: SourceMap } 或直接返回内容；异步通过 this.callback(err, code, map) 返回。

2. Loader 封装步骤（通用流程）

1. 初始化 Loader 文件（如 custom-loader.js），导出一个函数（同步）或异步函数；
2. 获取配置参数（通过 loader-utils 工具库，简化参数解析）；
3. 处理文件内容（核心逻辑：如替换字符串、编译语法、修改内容）；
4. 生成 SourceMap（可选，用 schema-utils 校验参数合法性，用 source-map 库生成 SourceMap）；
5. 返回处理结果（同步返回对象/字符串，异步调用回调）。

3. 实战 1：同步 Loader（简单字符串替换）

需求：封装一个 replace-loader，替换文件中指定字符串（如将 {``{ENV}} 替换为环境变量）。

步骤 1：安装依赖（工具库）

Loader 开发需 2 个核心工具库，必须安装：

npm install loader-utils schema-utils -D
# loader-utils：获取参数、处理路径等工具
# schema-utils：校验参数合法性（符合 JSON Schema 规范）

步骤 2：编写 Loader 核心代码（replace-loader.js）

// 1. 导入工具库
const { getOptions } = require('loader-utils'); // 获取 Loader 配置参数
const { validate } = require('schema-utils');   // 校验参数合法性

// 2. 定义参数校验规则（JSON Schema）：限制参数格式
const optionsSchema = {
  type: 'object',
  properties: {
    from: { type: 'string' }, // 要替换的字符串（必填）
    to: { type: 'string' }    // 替换后的字符串（必填）
  },
  required: ['from', 'to']    // 必传参数
};

// 3. 导出 Loader 函数（同步 Loader：函数返回处理结果）
module.exports = function (source) {
  // this 是 Webpack 注入的 Loader 上下文对象，包含丰富 API（如 query、resourcePath、callback 等）
  
  // ① 获取并校验参数
  const options = getOptions(this) || {}; // 获取配置参数
  validate(optionsSchema, options, { name: 'Replace Loader' }); // 校验参数，不合法则报错

  // ② 核心逻辑：替换字符串（source 是输入的文件内容）
  const result = source.replace(new RegExp(options.from, 'g'), options.to);

  // ③ 生成 SourceMap（可选，开发环境推荐，便于调试）
  const map = this.sourceMap ? {
    version: 3,
    file: this.resourcePath,
    sources: [this.resourcePath],
    sourcesContent: [source],
    mappings: 'AAAA' // 简单 SourceMap，复杂场景用 source-map 库生成
  } : null;

  // ④ 返回结果：同步返回 { code: 处理后内容, map: SourceMap }
  return { code: result, map: map };
};

步骤 3：Webpack 中配置使用 Loader

在 webpack.config.js 的 module.rules 中配置，支持链式调用（use 数组按「从后到前」执行）：

const path = require('path');

module.exports = {
  entry: './src/index.js',
  output: {
    filename: 'bundle.js',
    path: path.resolve(__dirname, 'dist')
  },
  module: {
    rules: [
      {
        test: /\.js$/, // 匹配所有 .js 文件
        exclude: /node_modules/, // 排除 node_modules（提升构建速度）
        use: [
          // 配置自定义 Loader，传递参数
          {
            loader: path.resolve(__dirname, './loaders/replace-loader.js'), // Loader 路径
            options: {
              from: '{{ENV}}', // 要替换的字符串
              to: process.env.NODE_ENV === 'production' ? 'production' : 'development' // 替换为环境变量
            }
          }
        ]
      }
    ]
  },
  mode: process.env.NODE_ENV || 'development'
};

步骤 4：测试使用

在 src/index.js 中写入：

console.log('当前环境：{{ENV}}');

执行构建命令 npm run build（需配置 package.json 脚本），打包后 dist/bundle.js 中会自动替换为：

console.log('当前环境：production'); // 生产环境

4. 实战 2：异步 Loader（文件读取+内容注入）

需求：封装一个 inject-file-loader，异步读取指定文件内容，注入到目标文件开头（如注入版权信息文件）。

核心代码（inject-file-loader.js）

异步 Loader 需通过 this.async() 获取回调函数，处理完异步逻辑后调用回调返回结果：

const { getOptions } = require('loader-utils');
const { validate } = require('schema-utils');
const fs = require('fs').promises; // 异步文件读取（推荐 promise 版）
const path = require('path');

// 参数校验规则：filePath 为要读取的文件路径（必填）
const optionsSchema = {
  type: 'object',
  properties: {
    filePath: { type: 'string' }
  },
  required: ['filePath']
};

// 导出异步 Loader 函数（async 函数）
module.exports = async function (source) {
  // ① 获取并校验参数
  const options = getOptions(this) || {};
  validate(optionsSchema, options, { name: 'Inject File Loader' });

  // ② 标记为异步 Loader，获取回调函数（async() 必须在同步代码中调用）
  const callback = this.async();

  try {
    // ③ 异步读取文件内容（核心异步逻辑）
    const injectContent = await fs.readFile(
      path.resolve(this.context, options.filePath), // this.context 是当前文件所在目录
      'utf-8' // 编码格式
    );

    // ④ 拼接内容：注入内容 + 原文件内容
    const result = `/* 注入的版权信息：*/\n${injectContent}\n\n${source}`;

    // ⑤ 异步返回结果（无错误则第一个参数传 null）
    callback(null, result, this.sourceMap ? { ...this.sourceMap } : null);
  } catch (err) {
    // ⑥ 错误处理：回调第一个参数传错误信息
    callback(err);
  }
};

Webpack 配置使用

module: {
  rules: [
    {
      test: /\.js$/,
      exclude: /node_modules/,
      use: [
        {
          loader: path.resolve(__dirname, './loaders/inject-file-loader.js'),
          options: {
            filePath: './src/copyright.txt' // 要注入的版权文件路径
          }
        },
        './loaders/replace-loader.js' // 链式调用：先执行 replace-loader，再执行 inject-loader（数组从后到前）
      ]
    }
  ]
}

5. Webpack Loader 核心 API（常用上下文 this 属性）

this 是 Webpack 注入的 Loader 上下文对象，包含关键 API，封装时必用：

• this.query：获取 Loader 配置参数（推荐用 loader-utils.getOptions(this) 替代，更友好）；
• this.resourcePath：当前处理文件的绝对路径（如 D:/project/src/index.js）；
• this.context：当前处理文件的所在目录（如 D:/project/src）；
• this.async()：标记为异步 Loader，返回回调函数（callback(err, code, map)）；
• this.sourceMap：布尔值，判断是否需要生成 SourceMap；
• this.emitFile(name, content)：生成新文件（如将处理后的资源输出到 dist 目录）；
• this.loadModule(request, callback)：加载其他模块（如依赖的文件）。

（二）Webpack Plugin 封装（流程增强）

1. Plugin 核心规范（必须遵守）

• 本质是类 ：Plugin 需封装为 Class，通过 apply 方法接入 Webpack 生命周期；
• 钩子触发 ：在 apply 方法中，通过 compiler.hooks 注册 Webpack 钩子，实现功能；
• 钩子类型 ：分「同步钩子」（tap 注册）和「异步钩子」（tapAsync/tapPromise 注册）；
• compiler & compilation ：
  • compiler：Webpack 实例，包含全局配置，生命周期贯穿整个构建；
  • compilation：单次构建的上下文，包含当前构建的资源、模块、依赖，每次编译（如文件修改重新构建）都会生成新的 compilation。

2. Plugin 封装步骤（通用流程）

1. 定义 Plugin 类，实现 apply 方法（接收 compiler 参数）；
2. 在 apply 中注册 Webpack 钩子（根据需求选择合适的钩子）；
3. 在钩子回调中实现核心逻辑（如修改资源、生成文件、打印日志）；
4. 处理异步逻辑（若钩子是异步，用 callback 或 Promise 完成）；
5. Webpack 配置中实例化 Plugin（可传递参数）。

3. 实战 1：同步 Plugin（打包完成后打印日志）

需求：封装 BuildLogPlugin，在 Webpack 打包完成后，打印构建耗时、输出目录等信息。

步骤 1：编写 Plugin 核心代码（BuildLogPlugin.js）

class BuildLogPlugin {
  // 构造函数：接收 Plugin 配置参数（如日志颜色、是否显示详细信息）
  constructor(options = {}) {
    // 默认配置
    this.defaultOptions = {
      color: 'green', // 日志颜色（green/red/blue）
      showDetail: true // 是否显示详细信息
    };
    // 合并用户配置与默认配置
    this.options = { ...this.defaultOptions, ...options };
  }

  // 核心方法：Webpack 会自动调用 apply，传入 compiler 实例
  apply(compiler) {
    // 1. 注册 Webpack 同步钩子：afterEmit（所有资源已输出到 dist 后触发）
    // 钩子文档：https://webpack.js.org/api/compiler-hooks/#afteremit
    compiler.hooks.afterEmit.tap('BuildLogPlugin', (compilation) => {
      // 2. 核心逻辑：计算构建耗时（compiler.startTime 是构建开始时间）
      const buildTime = Date.now() - compiler.startTime;

      // 3. 打印日志（根据配置自定义）
      console.log('\n================ 构建完成 ================\n');
      console.log(`📦 输出目录：${compiler.options.output.path}`);
      console.log(`⏱️  构建耗时：${buildTime}ms`);

      // 显示详细信息（模块数量、资源数量）
      if (this.options.showDetail) {
        const moduleCount = compilation.modules.length; // 处理的模块数量
        const assetCount = Object.keys(compilation.assets).length; // 输出的资源数量
        console.log(`📊 模块数量：${moduleCount} 个`);
        console.log(`🗂️  资源数量：${assetCount} 个`);
      }

      console.log('\n==========================================\n');
    });
  }
}

// 导出 Plugin 类
module.exports = BuildLogPlugin;

步骤 2：Webpack 中配置使用 Plugin

在 webpack.config.js 的 plugins 数组中实例化 Plugin，传递配置参数：

const BuildLogPlugin = require('./plugins/BuildLogPlugin');

module.exports = {
  // ... 其他配置
  plugins: [
    // 实例化自定义 Plugin，传递配置
    new BuildLogPlugin({
      color: 'blue',
      showDetail: true
    })
  ]
};

步骤 3：测试效果

执行 npm run build，打包完成后会在控制台输出：

================ 构建完成 ================

📦 输出目录：D:\project\dist
⏱️  构建耗时：320ms
📊 模块数量：12 个
🗂️  资源数量：3 个

==========================================

4. 实战 2：异步 Plugin（生成自定义文件）

需求：封装 GenerateFilePlugin，在打包完成后，异步生成一个 build-info.json 文件，包含构建时间、环境、版本等信息。

核心代码（GenerateFilePlugin.js）

异步钩子需用 tapAsync（回调方式）或 tapPromise（Promise 方式）注册，此处用 tapPromise 更简洁：

const fs = require('fs').promises;
const path = require('path');

class GenerateFilePlugin {
  constructor(options = {}) {
    this.options = {
      filename: 'build-info.json', // 生成的文件名
      outputDir: 'dist', // 输出目录（默认 dist）
      ...options
    };
  }

  apply(compiler) {
    // 注册异步钩子：afterEmit（用 tapPromise 注册，返回 Promise）
    compiler.hooks.afterEmit.tapPromise('GenerateFilePlugin', async (compilation) => {
      try {
        // 1. 构建要生成的文件内容（JSON 格式）
        const buildInfo = {
          buildTime: new Date().toISOString(), // 构建时间（ISO 格式）
          env: compiler.options.mode, // 构建环境（development/production）
          version: process.env.npm_package_version, // 项目版本（从 package.json 获取）
          outputPath: compiler.options.output.path // 输出路径
        };

        // 2. 拼接输出文件的绝对路径
        const outputPath = path.resolve(
          compiler.options.context, // 项目根目录
          this.options.outputDir,
          this.options.filename
        );

        // 3. 异步写入文件（核心异步逻辑）
        await fs.writeFile(outputPath, JSON.stringify(buildInfo, null, 2), 'utf-8');

        // 4. 日志提示
        console.log(`✅ 自定义文件已生成：${outputPath}`);
      } catch (err) {
        // 错误处理
        console.error('❌ 生成自定义文件失败：', err.message);
        throw err; // 抛出错误，终止构建（可选）
      }
    });
  }
}

module.exports = GenerateFilePlugin;

Webpack 配置使用

const GenerateFilePlugin = require('./plugins/GenerateFilePlugin');

module.exports = {
  // ... 其他配置
  plugins: [
    new GenerateFilePlugin({
      filename: 'build-info.json',
      outputDir: 'dist/static' // 输出到 dist/static 目录
    })
  ]
};

测试效果

打包后会在 dist/static/build-info.json 中生成文件：

{
  "buildTime": "2024-05-20T10:30:00.000Z",
  "env": "production",
  "version": "1.0.0",
  "outputPath": "D:\\project\\dist"
}

5. Webpack 核心钩子（常用，按生命周期分类）

（1）初始化阶段（compiler 钩子）

• entryOption：入口配置确定后触发（可修改入口）；
• afterPlugins：所有 Plugin 初始化完成后触发。

（2）编译阶段（compiler 钩子）

• compile：开始编译前触发；
• compilation：生成 compilation 实例后触发（常用，可获取编译上下文）。

（3）模块处理阶段（compilation 钩子）

• buildModule：开始构建模块前触发；
• moduleAsset：模块生成资源后触发。

（4）输出阶段（compiler 钩子）

• emit：资源输出到 dist 前触发（可修改输出资源）；
• afterEmit：资源输出完成后触发（常用，如生成额外文件、打印日志）；
• done：整个构建流程完成后触发。

三、Vite 生态封装（仅 Plugin，无 Loader）

Vite 无独立 Loader 概念，文件转换通过「Plugin + 预处理器」实现（如 SCSS 转 CSS 用 sass 包 + Vite 内置逻辑），Plugin 同时承担「文件转换」和「流程增强」能力，且兼容大部分 Rollup 插件（Vite 生产环境基于 Rollup 打包）。

1. Vite Plugin 核心规范（必须遵守）

• 本质是对象 ：Vite Plugin 是一个包含 name（插件名称，唯一）和钩子函数的对象，无需封装为类；
• 钩子分类：分「通用钩子」（开发/生产环境均生效）、「开发环境钩子」、「生产环境钩子」；
• 兼容 Rollup ：Vite Plugin 可复用 Rollup 插件的钩子（如 transform、generateBundle），也有 Vite 自定义钩子（如 configureServer 开发服务器配置）；
• 返回值 ：部分钩子支持返回修改后的数据（如 transform 返回修改后的文件内容），异步钩子支持 async/await。

2. Vite Plugin 封装步骤（通用流程）

1. 定义 Plugin 对象，指定 name（必填，唯一标识）；
2. 注册钩子函数（根据需求选择通用/开发/生产钩子）；
3. 在钩子中实现核心逻辑（文件转换、流程增强）；
4. Vite 配置中导入并添加到 plugins 数组。

3. 实战 1：通用 Plugin（文件内容转换，替代 Webpack Loader）

需求：封装 vite-plugin-replace，替换文件中指定字符串（如将 {``{VITE_ENV}} 替换为 Vite 环境变量），实现类似 Webpack replace-loader 的功能。

步骤 1：编写 Plugin 核心代码（vite-plugin-replace.js）

通过 transform 钩子实现文件转换（transform 钩子接收文件内容和路径，返回修改后的内容，类似 Webpack Loader）：

// Vite Plugin 是一个对象，包含 name 和钩子函数
export default function vitePluginReplace(options = {}) {
  // 默认配置
  const defaultOptions = {
    from: '',
    to: ''
  };
  const opts = { ...defaultOptions, ...options };

  return {
    name: 'vite-plugin-replace', // 插件名称（必填，唯一，用于调试和冲突检测）

    // 通用钩子：transform（文件转换，开发/生产环境均生效）
    // 接收参数：code（文件内容）、id（文件绝对路径）
    transform(code, id) {
      // 仅处理指定后缀的文件（如 .js、.vue），避免处理所有文件（提升性能）
      if (id.endsWith('.js') || id.endsWith('.vue')) {
        // 核心逻辑：替换字符串
        return code.replace(new RegExp(opts.from, 'g'), opts.to);
      }
      // 不处理的文件，直接返回 undefined（Vite 会使用原内容）
      return undefined;
    }
  };
}

步骤 2：Vite 中配置使用 Plugin

在 vite.config.js 中导入并配置：

import { defineConfig } from 'vite';
import vitePluginReplace from './plugins/vite-plugin-replace';
import path from 'path';

export default defineConfig(({ mode }) => {
  const isProd = mode === 'production';

  return {
    resolve: {
      alias: {
        '@': path.resolve(__dirname, 'src')
      }
    },
    plugins: [
      // 配置自定义 Plugin，传递参数
      vitePluginReplace({
        from: '{{VITE_ENV}}',
        to: isProd ? 'production' : 'development'
      })
    ],
    mode: mode
  };
});

步骤 3：测试效果

在 src/main.js 中写入：

console.log('Vite 环境：{{VITE_ENV}}');

执行 npm run dev（开发环境），浏览器控制台会输出：

Vite 环境：development

4. 实战 2：开发环境 Plugin（配置开发服务器，如接口代理增强）

需求：封装 vite-plugin-dev-server，在开发环境中添加自定义中间件（如拦截特定请求，返回模拟数据），增强 Vite 开发服务器功能。

核心代码（vite-plugin-dev-server.js）

通过 Vite 自定义钩子 configureServer 配置开发服务器（仅开发环境生效）：

export default function vitePluginDevServer(options = {}) {
  return {
    name: 'vite-plugin-dev-server',

    // Vite 自定义钩子：configureServer（开发环境生效，配置开发服务器）
    // 接收参数：server（Vite 开发服务器实例，基于 Connect 框架）
    configureServer(server) {
      // 添加自定义中间件（拦截 /api/mock 请求，返回模拟数据）
      server.middlewares.use('/api/mock', (req, res, next) => {
        // 设置响应头（JSON 格式）
        res.setHeader('Content-Type', 'application/json; charset=utf-8');
        // 返回模拟数据
        res.end(JSON.stringify({
          code: 200,
          message: '成功',
          data: {
            name: 'Vite 自定义中间件',
            time: new Date().toLocaleString()
          }
        }));
      });

      // 打印日志提示
      console.log('✅ 开发服务器中间件已加载：拦截 /api/mock 请求');
    }
  };
}

Vite 配置使用

import { defineConfig } from 'vite';
import vitePluginDevServer from './plugins/vite-plugin-dev-server';

export default defineConfig({
  // ... 其他配置
  plugins: [
    vitePluginDevServer() // 开发环境自动生效，生产环境忽略
  ]
});

测试效果

启动开发服务器 npm run dev，访问 http://localhost:5173/api/mock，会返回模拟 JSON 数据：

{
  "code": 200,
  "message": "成功",
  "data": {
    "name": "Vite 自定义中间件",
    "time": "2024-05-20 18:30:00"
  }
}

5. 实战 3：生产环境 Plugin（生成额外文件，替代 Webpack Plugin）

需求：封装 vite-plugin-generate-file，在生产环境打包完成后，生成 vite-build-info.json 文件，包含构建信息（类似 Webpack 的 GenerateFilePlugin）。

核心代码（vite-plugin-generate-file.js）

通过 Rollup 钩子 generateBundle 实现（生产环境打包时触发，生成额外文件）：

import fs from 'fs/promises';
import path from 'path';

export default function vitePluginGenerateFile(options = {}) {
  const defaultOptions = {
    filename: 'vite-build-info.json',
    outputDir: 'dist'
  };
  const opts = { ...defaultOptions, ...options };

  return {
    name: 'vite-plugin-generate-file',

    // Rollup 钩子：generateBundle（打包生成资源时触发，生产环境生效）
    // 接收参数：outputOptions（输出配置）、bundle（打包后的资源对象）
    async generateBundle(outputOptions, bundle) {
      // 1. 构建文件内容
      const buildInfo = {
        buildTime: new Date().toISOString(),
        env: process.env.NODE_ENV,
        version: process.env.npm_package_version,
        outputPath: outputOptions.dir // 输出目录
      };

      // 2. 拼接输出路径（outputOptions.dir 是 Vite 配置的 build.outDir）
      const outputPath = path.resolve(outputOptions.dir, opts.outputDir, opts.filename);

      // 3. 异步写入文件（确保目录存在，不存在则创建）
      await fs.mkdir(path.dirname(outputPath), { recursive: true });
      await fs.writeFile(outputPath, JSON.stringify(buildInfo, null, 2), 'utf-8');

      // 4. 日志提示（Vite 控制台输出）
      this.emitFile({
        type: 'asset',
        fileName: `static/${opts.filename}`, // 标记为静态资源（可选）
        source: JSON.stringify(buildInfo, null, 2)
      });
      console.log(`✅ 生产环境文件已生成：${outputPath}`);
    }
  };
}

Vite 配置使用

import { defineConfig } from 'vite';
import vitePluginGenerateFile from './plugins/vite-plugin-generate-file';

export default defineConfig({
  // ... 其他配置
  build: {
    outDir: 'dist' // 生产环境输出目录
  },
  plugins: [
    vitePluginGenerateFile({
      filename: 'vite-build-info.json',
      outputDir: 'static'
    })
  ]
});

测试效果

执行 npm run build，打包后会在 dist/static/vite-build-info.json 中生成文件，内容与 Webpack 案例一致。

6. Vite Plugin 核心钩子（常用分类）

（1）通用钩子（开发/生产均生效）

• transform(code, id)：文件转换（类似 Webpack Loader），修改文件内容；
• resolveId(source)：解析模块路径（如自定义别名、处理特殊模块）；
• load(id)：加载模块内容（如自定义模块加载逻辑）。

（2）开发环境钩子（仅 dev 生效）

• configureServer(server)：配置开发服务器（添加中间件、修改服务器配置）；
• transformIndexHtml(html)：修改入口 HTML 内容（如注入脚本、样式）。

（3）生产环境钩子（仅 build 生效，兼容 Rollup）

• generateBundle(outputOptions, bundle)：生成打包资源时触发（生成额外文件、修改资源）；
• writeBundle(outputOptions, bundle)：资源写入磁盘后触发；
• closeBundle()：打包流程完成后触发。

四、Vite vs Webpack 封装差异对比（快速选型）

对比维度	Webpack 封装	Vite 封装
Loader 支持	有，需单独封装 Loader 处理文件转换	无，文件转换通过 Plugin transform 钩子实现
Plugin 形式	类（需实现 apply 方法）	对象（含 name 和钩子函数）
核心钩子机制	基于 Tapable 事件流（钩子多，复杂）	基于 Rollup 钩子 + 自定义钩子（简洁）
开发环境特性	需配置 DevServer，Plugin 用 before/after 中间件	内置 DevServer，Plugin 用 configureServer 钩子
兼容性	生态成熟，Loader/Plugin 数量多	兼容大部分 Rollup 插件，生态快速增长
封装难度	中等（Loader/Plugin 需分别掌握）	简单（仅需掌握 Plugin，API 简洁）
调试体验	需配置 devtool，调试较复杂	原生 ESM 调试，支持源码映射，体验好

五、封装避坑指南（关键注意事项）

1. 性能优化

• 避免处理无关文件 ：Loader/Plugin 中通过 test（Webpack）或 id 判断（Vite），仅处理目标文件（如仅处理 .js 文件，排除 node_modules）；
• 异步逻辑优先：耗时操作（如文件读取、网络请求）用异步 Loader/Plugin，避免阻塞构建流程；
• 缓存机制 ：Webpack Loader 可通过 this.cacheable(false) 关闭缓存（默认开启），Vite 自动缓存，无需手动配置。

2. 错误处理

• 参数校验 ：必须用 schema-utils（Webpack）或自定义逻辑校验参数，避免非法参数导致构建失败；
• 异常捕获 ：异步逻辑必须用 try/catch 捕获错误，同步逻辑用 if 判断边界条件；
• 错误提示：错误信息需清晰（如标明插件名称、错误原因），便于排查问题。

3. 兼容性问题

• Webpack 版本：不同 Webpack 版本（4.x/5.x）钩子 API 可能变化，需明确兼容版本；
• Vite 版本：Vite 2.x/3.x/4.x 部分钩子有差异，优先适配最新稳定版；
• Rollup 兼容：Vite 生产环境基于 Rollup，封装生产环境 Plugin 需遵循 Rollup 规范。

4. 命名规范

• Loader 命名 ：Webpack Loader 命名格式为 xxx-loader（如 replace-loader），便于识别；
• Plugin 命名 ：Webpack Plugin 命名为 XXXPlugin（大驼峰，如 BuildLogPlugin），Vite Plugin 命名为 vite-plugin-xxx（如 vite-plugin-replace），符合社区规范。

六、总结

1. Webpack：适合复杂项目，需区分「Loader（文件转换）」和「Plugin（流程增强）」，Loader 链式执行，Plugin 基于 Tapable 钩子，生态成熟但封装稍复杂；
2. Vite：适合新项目，无 Loader 概念，Plugin 一站式解决所有需求，API 简洁，开发体验好，兼容 Rollup 插件；
3. 封装核心：Loader 专注「单一文件转换」，Plugin 专注「全流程增强」，无论哪种工具，都需遵循「单一职责、参数校验、错误处理、性能优化」原则。

掌握两种工具的封装能力，可轻松应对工程化中的自定义需求（如资源处理、流程优化、个性化功能），提升项目构建效率和可维护性。