提到 Webpack 5，大多数前端开发者会先想到持久化缓存、Module Federation 这些肉眼可见的升级点，但真正支撑起 Webpack 生态繁荣的，其实是它那套洋葱式的插件架构。Webpack 官方团队虽然很少直接用 Onion Architecture 这个词来宣传，但其插件系统的执行模型与洋葱模型高度一致：构建流程像洋葱一样一层层包裹，插件则是附着在每一层上的处理单元，资源在层层穿透中被逐步加工。理解这套架构，不仅能帮你写出更优雅的插件，也能让你在面对构建流程的各种疑难杂症时，快速定位问题发生在哪一层。
什么是洋葱架构：层层穿透的调用模型
洋葱架构最早由软件架构师 Jeffrey Palermo 在讨论领域驱动设计时提出，核心思想是把系统的核心逻辑放在最内层，外层依次包裹基础设施、接口适配等职责，依赖方向永远从外指向内。而前端社区更熟悉的版本，是 Koa 框架的洋葱中间件模型：一个请求进来，先从最外层中间件向内逐层执行前置逻辑，到达核心处理后再逐层向外执行后置逻辑，整个过程像穿过一颗洋葱。
Webpack 的构建流程恰好符合这个特征。它的核心是一个纯函数式的构建引擎，负责模块解析、依赖收集和产物生成这些内层能力；而外层则由 hundreds 个 hook 点组成，插件在 hook 上注册回调，就像在洋葱的某一层贴上了自己的处理逻辑。当构建流程执行到某个阶段，事件从内层发出，逐层触发外层插件的处理函数，处理完之后再继续向下传递，形成完整的进出闭环。
与传统的管道（Pipeline）架构相比，洋葱模型最大的优势在于每个插件既能在资源处理之前介入，也能在处理之后介入。比如你可以在 emit 阶段拦截输出文件做压缩，也可以在输出完成后再做一次校验，两个时机都在同一个插件的 apply 方法里声明，控制流清晰且不侵入核心代码。
Webpack 5 中洋葱架构的载体：Tapable 事件系统
Webpack 5 的插件能力建立在 Tapable 这个事件总线库之上。compiler 和 compilation 两个对象几乎承载了全部的 hook，每个 hook 都有明确的类型语义：SyncHook 表示同步串行执行，AsyncSeriesHook 表示异步串行执行，AsyncParallelHook 表示异步并行执行。这些 hook 类型决定了同一层上多个插件的调度顺序，也决定了洋葱每一层的穿透方式。
下面这段代码演示了如何注册一个典型的插件。apply 方法是插件接入洋葱架构的唯一入口，Webpack 在初始化 compiler 时会调用它，把 hooks 的注册权交给插件开发者：
class MyPlugin {
apply(compiler) {
// 外层介入：编译开始前
compiler.hooks.thisCompilation.tap('MyPlugin', (compilation) => {
console.log('compilation 创建');
});
// 异步介入：输出资源前，next 之前的逻辑是前置阶段
compiler.hooks.emit.tapAsync('MyPlugin', (compilation, callback) => {
// 前置处理：遍历即将输出的资源
for (const name of Object.keys(compilation.assets)) {
console.log('处理资源: ' + name);
}
// 模拟异步操作，完成后调用 callback 相当于进入洋葱下一层
setTimeout(() => {
callback();
}, 100);
});
}
}
module.exports = MyPlugin;</code>这段代码里的 callback 调用非常关键，它就是洋葱模型中的 next。在 tapAsync 注册的回调里，callback 之前的代码是前置逻辑，callback 之后还可以书写后置逻辑，形成完整的进出结构。如果某个插件忘记调用 callback，整条洋葱链就会卡死，这也是新手写插件时最常见的坑。
Webpack 5 相比 4.x 在 hook 的调度上做了不少优化，比如缓存阶段的 hook 细分更完善，增加了 processAssets 这类带阶段参数的 hook，让插件能明确声明自己在处理链中的位置，这其实是对洋葱分层语义的进一步强化。
动手实践：用洋葱模型写一个资源处理插件
理解了架构之后，最有效的巩固方式是自己写一个插件。下面实现一个在产物输出时自动给 JS 文件头部注入构建时间注释的插件，它完整展示了前置介入、异步等待、后置处理的洋葱式流程：
class BuildStampPlugin {
apply(compiler) {
compiler.hooks.processAssets.tapPromise(
{
name: 'BuildStampPlugin',
stage: compiler.Compilation.PROCESS_ASSETS_STAGE_SUMMARIZE,
},
async (assets) => {
for (const [name, source] of Object.entries(assets)) {
if (!name.endsWith('.js')) continue;
const code = source.source().toString();
const stamped = '/* build at ' + new Date().toISOString() + ' */\n' + code;
// 替换资源，相当于在洋葱向外返回的路径上修改产物
assets[name] = {
source: () => stamped,
size: () => stamped.length,
};
}
}
);
}
}
module.exports = BuildStampPlugin;</code>这里用到的 processAssets 是 Webpack 5 推荐的资源处理入口，它替代了旧版的 emit 阶段直接改 assets 的做法。stage 参数决定了插件在处理链中的层级，数值越小越靠近洋葱内层，多个插件可以通过 stage 精确编排执行顺序，避免互相覆盖。
在使用时只需在配置中挂载：
const BuildStampPlugin = require('./build-stamp-plugin');
module.exports = {
plugins: [new BuildStampPlugin()],
};洋葱架构带来的设计启示与常见误区
洋葱架构给 Webpack 带来的最大价值是开放封闭原则的落地：核心构建引擎不需要为每种需求修改代码，新增能力只需新增一层。代码压缩、sourcemap 生成、HTML 注入，全部都是以插件形式存在于生态中的。这也解释了为什么 Webpack 能长期统治复杂工程场景，它的架构天然鼓励横向扩展。
不过实践中也有几个容易踩的误区。第一是滥用 AsyncParallelHook 场景下的共享状态，多个插件并行处理同一份 compilation 对象时，修改共享数据必须考虑原子性。第二是 hook 的时机选择错误，比如想在模块解析前修改源码，应该用 NormalModuleFactory 的 beforeResolve 而不是 compilation 的 seal 之后阶段，选错层级往往导致改动不生效。第三是忽略 Webpack 5 的 stage 机制，多个插件争夺同一资源时如果不显式声明 stage，执行顺序取决于注册顺序，稳定性会很差。
总的来说，Webpack 5 的洋葱架构是一种经过工程验证的分层思想，它把构建流程拆成可插拔的洋葱层，让复杂度可控、能力可扩展。当你下次面对一个奇怪的资源产物问题时，不妨顺着洋葱的层次，从 compiler 到 compilation 再到具体的 hook 逐层排查，往往比盲目搜索报错信息高效得多。