插件开发进阶与Hook架构

const PLUGIN_NAME = "FooPlugin";

class FooPlugin {
  apply(compiler) {
    compiler.hooks.compilation.tap(PLUGIN_NAME, (compilation) => {
      const logger = compilation.getLogger(PLUGIN_NAME);
    });
  }
}

verbose < log < info < warn < error

const logger = compilation.getLogger(PLUGIN_NAME);

logger.verbose('详细调试信息，仅在 verbose 级别显示');
logger.log('常规运行日志');
logger.info('信息提示');
logger.warn('警告信息');
logger.error('错误信息');

module.exports = {
  infrastructureLogging: {
    level: 'log',     // 控制台输出的最低级别
    debug: false,      // 是否开启调试模式
    trace: false,      // 是否追踪日志调用栈
    stream: process.stderr, // 输出流
  },
};

class FooPlugin {
  apply(compiler) {
    compiler.hooks.compilation.tap(PLUGIN_NAME, (compilation) => {
      if (!this.validateOptions()) {
        compilation.errors.push(
          new Error(`${PLUGIN_NAME}: 配置参数无效`)
        );
      }
      if (this.hasDeprecation()) {
        compilation.warnings.push(
          `${PLUGIN_NAME}: 当前选项即将废弃`
        );
      }
    });
  }
}

const { WebpackError } = require('webpack');

class FooPlugin {
  apply(compiler) {
    compiler.hooks.compilation.tap(PLUGIN_NAME, (compilation) => {
      compilation.hooks.buildModule.tap(PLUGIN_NAME, (module) => {
        try {
          this.processModule(module);
        } catch (err) {
          const error = new WebpackError(`${PLUGIN_NAME}: 处理模块失败（${module.identifier()}）`);
          error.details = err.stack; // details 字段携带额外上下文
          compilation.errors.push(error);
        }
      });
    });
  }
}

class ImageminPlugin {
  apply(compiler) {
    const onEmit = async (compilation, callback) => {
      try {
        await this.optimizeImages(compilation);
        callback();
      } catch (err) {
        callback(err); // 透传给 Webpack 处理
      }
    };
    compiler.hooks.emit.tapAsync(this.constructor.name, onEmit);
  }
}

class FooPlugin {
  apply(compiler) {
    compiler.hooks.compilation.tap(PLUGIN_NAME, () => {
      throw new Error('致命错误，必须终止构建');
    });
  }
}

需要中断构建？
├── 是 → 直接 throw Error
└── 否 ├── 需要记录模块级错误？
│       └── 是 → new CompilationModuleError(module, err)
│       └── 否 ├── 需要结构化错误？
│               └── 是 → new WebpackError(details)
│               └── 否 → compilation.errors.push(...)

const { validate } = require("schema-utils");

const schema = {
  type: "object",
  properties: {
    test: {
      type: "string",
      minLength: 1,
    },
    exclude: {
      type: "array",
      items: { type: "string" },
    },
  },
  additionalProperties: false,
};

class FooPlugin {
  constructor(options = {}) {
    validate(schema, options, {
      name: "Foo Plugin",
      baseDataPath: "options",
    });
    this.options = options;
  }
}

class FooPlugin {
  constructor(options = {}) {
    this.options = options;
  }

  apply(compiler) {
    compiler.hooks.validate.tap("FooPlugin", () => {
      // 由 webpack 统一执行并报告校验错误（内置插件如 BannerPlugin 即此用法）
      compiler.validate(
        () => require("./plugin.schema.json"),
        this.options,
        { name: "Foo Plugin", baseDataPath: "options" },
        (options) => require("./plugin.schema.check")(options) // 预编译检查函数（可选）
      );
    });
  }
}

{
  "name": "foo-webpack-plugin",
  "peerDependencies": {
    "webpack": "^5.0.0"
  }
}

class FooPlugin {
  apply(compiler) {
    const webpackVersion = typeof compiler.webpack === 'function'
      ? compiler.webpack.version
      : require('webpack/package.json').version;

    const majorVersion = parseInt(webpackVersion.split('.')[0], 10);

    if (majorVersion !== 5) {
      throw new Error(
        `${PLUGIN_NAME}: 此插件仅支持 Webpack 5.x，当前版本 ${webpackVersion}`
      );
    }

    // 检测特定功能是否可用
    if (typeof compiler.hooks.validate === 'undefined') {
      console.warn(`${PLUGIN_NAME}: 当前 Webpack 版本不支持 validate hook`);
    }
  }
}

const { ProgressPlugin } = require("webpack");
const PLUGIN_NAME = "HeavyPlugin";
const noop = () => ({});

class HeavyPlugin {
  apply(compiler) {
    compiler.hooks.compilation.tap(PLUGIN_NAME, (compilation) => {
      compilation.hooks.processAssets.tapAsync(
        { name: PLUGIN_NAME, stage: compiler.webpack.Compilation.PROCESS_ASSETS_STAGE_OPTIMIZE },
        async (assets, callback) => {
          const reportProgress = ProgressPlugin.getReporter(compiler) || noop;
          const tasks = Object.keys(assets);

          for (let i = 0; i < tasks.length; i++) {
            await this.processAsset(tasks[i]);
            reportProgress(i / tasks.length, `[${PLUGIN_NAME}] 处理 ${tasks[i]}`);
          }
          reportProgress(1, `[${PLUGIN_NAME}] 完成`);
          callback();
        }
      );
    });
  }
}

class FooPlugin {
  apply(compiler) {
    compiler.hooks.compilation.tap(PLUGIN_NAME, (compilation) => {
      const timingMap = new Map();

      compilation.hooks.buildModule.tap(PLUGIN_NAME, (module) => {
        const start = Date.now();
        this.processModule(module);
        timingMap.set(module.identifier(), Date.now() - start);
      });

      compilation.hooks.statsFactory.tap(PLUGIN_NAME, (factory) => {
        factory.hooks.result.for("module").tap(PLUGIN_NAME, (module, context) => {
          module[`${PLUGIN_NAME}Duration`] = timingMap.get(module.identifier()) || 0;
        });
      });

      compilation.hooks.statsPreset.tap(PLUGIN_NAME, (result, context) => {
        result[`${PLUGIN_NAME}Summary`] = {
          totalProcessed: timingMap.size,
          avgDuration: Array.from(timingMap.values())
            .reduce((a, b) => a + b, 0) / timingMap.size || 0,
        };
      });
    });
  }
}

{
  "modules": [
    {
      "identifier": "./src/index.js",
      "fooPluginDuration": 124
    }
  ],
  "fooPluginSummary": {
    "totalProcessed": 42,
    "avgDuration": 87.3
  }
}

const { SyncHook } = require("tapable");

// Step 1: 创建钩子实例
const sleep = new SyncHook();

// Step 2: 订阅接口注册回调（tap / tapAsync / tapPromise）
sleep.tap("test", () => {
  console.log("callback A");
});

// Step 3: 发布接口触发回调（call / callAsync / promise）
sleep.call();

const { SyncHook } = require("tapable");

const hook = new SyncHook(["arg1", "arg2"]);

hook.tap("A", (arg1, arg2) => console.log(`A: ${arg1}, ${arg2}`));
hook.tap("B", (arg1, arg2) => console.log(`B: ${arg1}, ${arg2}`));

hook.call("hello", "world");
// A: hello, world
// B: hello, world

function syncCall() {
  const callbacks = [fn1, fn2, fn3];
  for (let i = 0; i < callbacks.length; i++) {
    callbacks[i](...args);
  }
}

const { SyncBailHook } = require("tapable");

const hook = new SyncBailHook(["value"]);

hook.tap("validator", (value) => {
  if (value < 0) return { valid: false };
});

hook.tap("transformer", (value) => {
  return value * 2;
});

const result = hook.call(5);
console.log(result); // 10

const result2 = hook.call(-1);
console.log(result2); // { valid: false } ← 在 validator 处熔断

function bailCall() {
  for (const cb of callbacks) {
    const result = cb(...args);
    if (result !== undefined) return result;
  }
  return undefined;
}

const { SyncWaterfallHook } = require("tapable");

const hook = new SyncWaterfallHook(["value"]);

hook.tap("addOne", (val) => {
  console.log(`addOne 收到: ${val}`);
  return val + 1;
});

hook.tap("double", (val) => {
  console.log(`double 收到: ${val}`);
  return val * 2;
});

const result = hook.call(1);
// addOne 收到: 1
// double 收到: 2
console.log(`最终结果: ${result}`); // 4

const { SyncLoopHook } = require("tapable");

const hook = new SyncLoopHook();

let count = 0;

hook.tap("retry", () => {
  count++;
  console.log(`第 ${count} 次执行`);
  return count < 3 ? count : undefined; // 返回非 undefined 则继续循环
});

hook.tap("done", () => console.log("全部完成"));

hook.call();
// 第 1 次执行
// 第 2 次执行
// 第 3 次执行
// 全部完成

const { AsyncSeriesHook } = require("tapable");

const hook = new AsyncSeriesHook();

// callback 风格
hook.tapAsync("A", (cb) => {
  setTimeout(() => {
    console.log("A 完成");
    cb();
  }, 100);
});

// promise 风格
hook.tapPromise("B", () => {
  return new Promise((resolve) => {
    setTimeout(() => {
      console.log("B 完成");
      resolve();
    }, 100);
  });
});

hook.callAsync(() => console.log("全部结束"));
// A 完成 → B 完成 → 全部结束

const { AsyncParallelHook } = require("tapable");

const hook = new AsyncParallelHook();

hook.tapAsync("A", (cb) => {
  setTimeout(() => { console.log("A"); cb(); }, 100);
});

hook.tapAsync("B", (cb) => {
  setTimeout(() => { console.log("B"); cb(); }, 50);
});

hook.callAsync(() => console.log("结束"));
// B → A → 结束（B 先完成但不阻塞 A）

(function anonymous(name, _callback) {
  "use strict";
  var _x = this._x;

  function _next1() {
    var _fn2 = _x[2];
    _fn2(name, function(_err2, _result2) {
      if (_err2) {
        _callback(_err2);
      } else {
        if (_result2 !== undefined) name = _result2;
        _callback(null, name);
      }
    });
  }

  function _next0() {
    var _fn1 = _x[1];
    _fn1(name, function(_err1, _result1) {
      if (_err1) {
        _callback(_err1);
      } else {
        if (_result1 !== undefined) name = _result1;
        _next1();
      }
    });
  }

  var _fn0 = _x[0];
  _fn0(name, function(_err0, _result0) {
    if (_err0) {
      _callback(_err0);
    } else {
      if (_result0 !== undefined) name = _result0;
      _next0();
    }
  });
});

hook.intercept({
  call: (...args) => {
    console.log("call/callAsync/promise 被调用时触发");
  },

  tap: (tap) => {
    console.log(`每个回调执行前触发, 当前: ${tap.name}`);
  },

  loop: (...args) => {
    console.log("每次循环迭代开始前触发（仅 Loop 型有效）");
  },

  register: (tap) => {
    console.log("每次 tap/tapAsync/tapPromise 被调用时触发");
    tap.context = { customData: true }; // 可修改 tap 信息
    return tap; // 返回修改后的 tap（返回 undefined 则沿用原 tap）
  },
});

class ProgressInterceptor {
  static applyTo(hook, reporter) {
    let total = 0;
    let current = 0;

    hook.intercept({
      register: () => { total++; },
      call: () => { current = 0; },
      tap: (tap) => {
        current++;
        reporter(current / total, `${tap.name}`);
      },
    });
  }
}

ProgressInterceptor.applyTo(compilation.hooks.processAssets, reportProgress);

hook.intercept({
  register: (tap) => {
    if (!allowedPlugins.includes(tap.name)) {
      // register 无法取消注册（返回 undefined 只会沿用原 tap），
      // 这里用空实现替换原回调并告警，实现"软拦截"
      console.warn(`[hook] 未授权的插件尝试注册: ${tap.name}`);
      return { ...tap, fn: () => {} };
    }
    return tap;
  },
});

hook.intercept({
  call: () => { this._startTime = Date.now(); },
  tap: (tap) => {
    const start = Date.now();
    return {
      ...tap,
      fn: (...args) => {
        const result = tap.fn(...args);
        console.log(`${tap.name} 耗时: ${Date.now() - start}ms`);
        return result;
      },
    };
  },
});

const { SyncHook, HookMap } = require("tapable");

const map = new HookMap((key) => new SyncHook(["data"]));

// 通过 for 指定 key 进行注册
map.for("javascript").tap("JsHandler", (data) => { /* ... */ });
map.for("css").tap("CssHandler", (data) => { /* ... */ });
map.for("html").tap("HtmlHandler", (data) => { /* ... */ });

// 通过 get 获取指定 key 的 Hook 并触发
map.get("javascript").call(someData);

class Parser {
  constructor() {
    this.hooks = {
      expression: new HookMap(() => new SyncBailHook(["expression"])),
    };
  }

  walkMemberExpression(expression) {
    const exprName = this.getNameForExpression(expression);
    if (exprName?.free) {
      const hook = this.hooks.expression.get(exprName.name);
      if (hook !== undefined) {
        const result = hook.call(expression);
        if (result === true) return;
      }
    }
  }
}

class CommonJsStuffPlugin {
  apply(compiler) {
    compiler.hooks.compilation.tap("CJS", (compilation, { normalModuleFactory }) => {
      normalModuleFactory.hooks.parser
        .for("javascript/auto")
        .tap("CJS", (parser, parserOptions) => {
          parser.hooks.expression
            .for("require.main")
            .tap("CJS", ParserHelpers.toConstantDependency(parser, "..."));

          parser.hooks.expression
            .for("__dirname")
            .tap("CJS", ParserHelpers.toConstantDependency(parser, "__dirname"));
        });
    });
  }
}

const { SyncHook, MultiHook } = require("tapable");

const hook1 = new SyncHook();
const hook2 = new SyncHook();
const hook3 = new SyncHook();

const multi = new MultiHook([hook1, hook2, hook3]);

multi.tap("sharedCallback", () => {
  console.log("这个回调会注册到 hook1, hook2, hook3");
});

const { SyncHook, AsyncSeriesHook } = require("tapable");

class CustomPlugin {
  apply(compiler) {
    // 扩展 Compiler hooks
    compiler.hooks.myCustomHook = new SyncHook(["data"]);

    // 扩展 Compilation hooks
    compiler.hooks.compilation.tap("CustomPlugin", (compilation) => {
      compilation.hooks.myCustomCompilationHook = new AsyncSeriesHook(["asset"]);
    });

    // 使用自定义 Hook
    compiler.hooks.myCustomHook.tap("CustomPlugin", (data) => {
      console.log("自定义 Compiler Hook 触发:", data);
    });
  }
}

compilation.hooks.processAssets.tap(
  {
    name: "MyPlugin",
    stage: compiler.webpack.Compilation.PROCESS_ASSETS_STAGE_OPTIMIZE, // 数值越小越先执行
  },
  (assets) => { /* ... */ }
);

import path from "path";
import webpack from "webpack";
import { merge } from "webpack-merge";
import { createFsFromVolume, Volume } from "memfs";

export function runCompile(options) {
  const config = merge(
    {
      mode: "development",
      devtool: false,
      entry: path.join(__dirname, "./fixtures/entry.js"),
      output: { path: path.resolve(__dirname, "../dist") },
    },
    options
  );

  const compiler = webpack(config);
  compiler.outputFileSystem = createFsFromVolume(new Volume());

  return new Promise((resolve, reject) => {
    compiler.run((error, stats) => {
      if (error) return reject(error);
      resolve({ stats, compiler });
    });
  });
}

import path from "path";
import { promisify } from "util";
import { runCompile } from "./helpers";
import FooPlugin from "../src/FooPlugin";

describe("FooPlugin", () => {
  it("should work without errors", async () => {
    const { stats } = await runCompile({
      plugins: [new FooPlugin()],
    });

    expect(stats.hasErrors()).toBe(false);
    expect(stats.hasWarnings()).toBe(false);
  });

  it("should inject banner to output assets", async () => {
    const { stats, compiler } = await runCompile({
      plugins: [new FooPlugin({ banner: "// Injected by FooPlugin" })],
    });

    const { outputPath } = stats.compilation.options.output;
    const assets = stats.toJson().assetsByChunkName;

    for (const name of Object.values(assets)) {
      const filePath = path.join(outputPath, name);
      const content = await promisify(compiler.outputFileSystem.readFile)(
        filePath,
        { encoding: "utf-8" }
      );
      expect(content).toContain("// Injected by FooPlugin");
    }
  });

  it("should report warning for invalid option", async () => {
    const { stats } = await runCompile({
      plugins: [new FooPlugin({ invalidOption: true })],
    });

    expect(stats.hasWarnings()).toBe(true);
  });

  it("should handle empty entry gracefully", async () => {
    const { stats } = await runCompile({
      entry: {},
      plugins: [new FooPlugin()],
    });

    expect(stats.hasErrors()).toBe(false);
  });
});

yarn add -D jest babel-jest @babel/core @babel/preset-env memfs webpack-merge webpack

module.exports = {
  presets: [['@babel/preset-env', { targets: { node: 'current' } }]],
};

module.exports = {
  testEnvironment: "node",
  testMatch: ["<rootDir>/test/**/*.test.js"],
};