Webpack 5 新特性如何助力 Clean Architecture 整洁架构落地？

整洁架构（Clean Architecture）由 Robert C. Martin 提出，核心思想是把系统划分成不同层次的同心圆，业务逻辑位于最内层，框架、数据库、UI 等基础设施位于外层，依赖方向只能由外向内。前端项目长期受困于业务代码与框架代码纠缠不清的状态，组件里直接调用接口、工具函数里耦合了路由逻辑的情况屡见不鲜。Webpack 5 虽然是一个构建工具，但它提供的模块联邦、更彻底的 Tree Shaking、嵌套的 tree-shaking 能力以及持久化缓存等特性，恰好为在工程层面落实整洁架构提供了抓手。本文将围绕这些能力，讨论如何在真实项目中落地分层与解耦。

一、整洁架构在前端工程中的依赖规则

在深入 Webpack 配置之前，先明确依赖规则在目录层面的表达。整洁架构最核心的一条原则是：源码依赖只能指向内层，内层不允许知道外层的存在。映射到前端项目，可以划分为 entities（实体与领域逻辑）、use-cases（用例层）、adapters（适配器层）以及 frameworks（框架与基础设施层）四层。UI 组件属于最外层，可以调用 use-cases 暴露的方法，而 use-cases 只依赖 entities，绝不 import 任何 React 组件或 axios 实例。

这条规则如果只靠口头约定，很快就会被违反。Webpack 的 resolve.alias 配合 ESLint 的 import 插件，可以把依赖方向固化为构建约束。例如把内层模块映射成短路径，同时利用 NormalModuleReplacementPlugin 在构建阶段拦截违规引用，一旦某个 entities 文件试图引用 adapters 下的内容，构建直接失败。这种做法把架构图从文档变成了可执行的规则，是工程化落地的第一步。

需要注意的是，依赖规则约束的是模块间的静态引用，而不是运行时的数据流动。事件、回调这类由外层注入内层的控制反转手段依然合法，也是保持内层纯净的关键技巧。

二、用 Tree Shaking 增强保持内层零副作用

整洁架构要求内层代码是纯的业务逻辑，这恰好与 Webpack 5 对 Tree Shaking 的增强要求不谋而合。Webpack 5 引入了嵌套的 Tree Shaking 和对 CommonJS 的部分分析能力，能够追踪模块内部导出对象属性的逐级使用情况。只要领域层代码遵守纯函数风格、不触发副作用，未被用例引用的领域函数会被自动从产物中剔除，内层的纯粹性直接转化为包体积的收益。

来看一个典型的配置示例，通过 sideEffects 字段与压缩配置配合，让 Tree Shaking 发挥最大效果：

// package.json
{
  "name": "my-app",
  "sideEffects": false
}

// webpack.config.js
module.exports = {
  mode: 'production',
  optimization: {
    usedExports: true,
    concatenateModules: true,
    minimize: true
  },
  experiments: {
    topLevelAwait: true
  }
};

在领域层避免副作用还有一个隐蔽的好处：测试速度。纯函数模块不依赖 DOM 和网络，单测可以毫秒级完成，这与整洁架构强调的用例可测试性形成正反馈。反过来，如果在 entities 里偷偷调用了全局对象，Tree Shaking 会失效，测试也需要模拟浏览器环境，架构腐化的信号往往就从这些细节开始。

三、模块联邦：按架构边界拆分独立部署单元

模块联邦（Module Federation）是 Webpack 5 最具架构意义的新特性，它允许多个独立构建的应用在运行时共享模块。从整洁架构视角看，它的价值不在于微前端本身，而在于把系统的边界（Boundary）变成了物理隔离的构建单元。每个团队负责一个边界内的完整层次，对外只暴露经过设计的公共接口，内部实现随时可以重写而不影响消费方。

下面是一个将订单领域作为远程模块暴露的配置示例：

// order-service 的 webpack.config.js
const { ModuleFederationPlugin } = require('webpack').container;

module.exports = {
  plugins: [
    new ModuleFederationPlugin({
      name: 'orderService',
      filename: 'remoteEntry.js',
      exposes: {
        // 只暴露用例层入口，不暴露内部实现
        './use-cases': './src/use-cases/index.ts'
      },
      shared: {
        react: { singleton: true },
        'react-dom': { singleton: true }
      }
    })
  ]
};

关键实践在于 exposes 只暴露 use-cases 层的入口文件，相当于为远程模块定义了一层防腐接口。消费方拿到的永远是稳定的用例签名，订单服务内部的仓储实现、缓存策略如何调整都与其无关。这与整洁架构中插件应通过边界接口通信的原则完全一致。

另外，shared 配置使用 singleton 保证宿主与远程之间只有一份 React 实例，避免了多副本带来的状态分裂问题，这是模块联邦落地时必须处理的共享依赖策略。

四、持久化缓存保障架构重构的可持续性

架构重构往往伴随着大规模的文件移动和 import 路径修改，如果每次改动都触发全量构建，团队很快会失去重构耐心。Webpack 5 的文件系统缓存基于内容寻址，配合 buildDependencies 和 snapshot 管理，能够在重构后命中大部分模块缓存，把增量构建控制在秒级。这看似只是性能优化，实际上决定了架构演进能否持续进行。

// webpack.config.js
module.exports = {
  cache: {
    type: 'filesystem',
    buildDependencies: {
      // 配置文件变化时使缓存失效
      config: [__filename]
    },
    cacheDirectory: 'node_modules/.cache/webpack'
  }
};

值得一提的是，模块联邦与持久化缓存叠加时要注意远程模块的版本协商。远程端的 remoteEntry.js 更新后，宿主端缓存的旧模块可能产生不一致，建议在 CI 中对远程入口的哈希做版本锁定，并在发布流水线中加入契约测试，确保暴露的用例接口没有被意外破坏。

五、推荐的项目目录结构

最后给出一个可直接套用的分层目录结构，配合前文的 alias 与插件约束使用：

src/
  entities/            # 领域实体与纯业务规则
    order.ts
    product.ts
  use-cases/           # 应用层用例，编排领域逻辑
    create-order.ts
    index.ts           # 对外唯一出口
  adapters/            # 适配器：API、存储、第三方服务
    order-api.ts
    local-storage.ts
  frameworks/          # 框架层：组件、路由、DI 容器
    components/
    containers/
    di.ts              # 依赖注入，把适配器装配进用例
  main.ts              # 组装根

装配是单向的：main.ts 读取环境配置，在 DI 容器中把具体的 API 适配器注入用例工厂，UI 组件只消费容器返回的用例实例。这样一来，把 axios 换成 fetch、把 REST 换成 GraphQL，改动范围被严格限制在 adapters 目录内，这正是整洁架构追求的替换自由度。

总结来看，Webpack 5 本身并不提供架构，但它提供的模块联邦、增强的 Tree Shaking 和持久化缓存，让分层规则可以被工程工具强制执行，让边界可以独立部署，让重构可以低成本迭代。工具与思想的配合，才是整洁架构在前端真正落地的路径。

Webpack 5Clean Architecture前端工程化修改时间：2026-09-08 09:49:05