微前端架构这几年热度一直不低，但落地时最棘手的问题往往是代码共享。A 应用写好了一套业务组件，B 应用想直接使用，传统做法要么发 npm 包再各自构建，要么把代码复制一份，前者迭代链路长，后者维护成本高。Webpack 5 引入的 Module Federation（模块联邦）就是为了解决这个问题而生的，它允许多个独立构建、独立部署的应用在运行时动态共享模块，不需要打包进各自的 bundle 里。本文会从核心概念、配置实战、运行时原理和落地注意事项几个角度，把这个特性讲透。
Module Federation 的三个核心概念
理解 Module Federation 的第一步是分清三个角色：容器（container）、远程模块（remote）和共享依赖（shared）。容器本质上是一个经过特殊处理的 bundle，它对外暴露了一组模块的访问入口，同时携带一份模块映射表。远程模块指的是从其他容器动态加载进来的代码，对宿主应用来说，它和本地模块的使用体验几乎一致，import 什么就得到什么。共享依赖则解决的是公共库重复加载的问题，比如两个应用都用 React，如果各自打包一份，页面会同时存在两份 React 实例，不仅体积翻倍，还会导致 hooks 报错等运行时异常。
这三个概念的关系可以这样理解：每个参与联邦的应用既是潜在的提供方，也是潜在的消费方。一个应用通过 exposes 把自己的某些模块暴露出去，就成为了 remote 提供者；通过 remotes 声明要引用哪些外部容器，就成为了 host 消费者；通过 shared 声明哪些依赖可以共享，交由运行时协商决定最终用谁的副本。
值得注意的是，这种模式打破了“构建时必须确定所有依赖”的传统假设。过去 Webpack 的代码分割只能在同一个构建上下文里进行，Module Federation 把这个边界扩展到了跨应用、跨团队、跨部署单元的场景，这正是它被称作微前端利器的原因。
完整配置示例：宿主应用加载远程模块
下面通过一个具体例子演示配置方式。假设有两个应用：app1 是宿主（host），app2 是远程提供方（remote）。app2 暴露一个按钮组件，app1 在页面里直接使用它。先看 app2 的配置：
// app2/webpack.config.js
const { ModuleFederationPlugin } = require('webpack').container;
module.exports = {
// devServer 需要开启跨域支持，宿主应用才能加载远程脚本
devServer: { headers: { 'Access-Control-Allow-Origin': '*' } },
plugins: [
new ModuleFederationPlugin({
name: 'app2',
filename: 'remoteEntry.js',
// 对外暴露的模块，key 是外部访问路径，value 是模块内部路径
exposes: {
'./Button': './src/components/Button',
},
// 声明可共享的依赖及其版本要求
shared: {
react: { singleton: true, requiredVersion: '^18.0.0' },
'react-dom': { singleton: true, requiredVersion: '^18.0.0' },
},
}),
],
};
app1 这边需要在 remotes 里声明对 app2 的引用，同时在页面代码里通过异步方式加载远程模块：
// app1/webpack.config.js
const { ModuleFederationPlugin } = require('webpack').container;
module.exports = {
plugins: [
new ModuleFederationPlugin({
name: 'app1',
remotes: {
app2: 'app2@http://localhost:3002/remoteEntry.js',
},
shared: {
react: { singleton: true, requiredVersion: '^18.0.0' },
'react-dom': { singleton: true, requiredVersion: '^18.0.0' },
},
}),
],
};
// app1/src/App.jsx
import React, { Suspense } from 'react';
// 远程组件的引入方式与本地组件一致，注意路径要带 remote 名称前缀
const RemoteButton = React.lazy(() => import('app2/Button'));
export default function App() {
return (
<div>
<h1>宿主应用</h1>
<Suspense fallback={<div>加载远程组件中...</div>}>
<RemoteButton />
</Suspense>
</div>
);
}
这段配置里有几个细节值得展开。第一，filename 指定的 remoteEntry.js 是容器的入口文件，宿主加载它之后才能拿到模块映射表，再按需加载真正的业务代码。第二，singleton: true 表示这个依赖全局只允许存在一个实例，如果宿主和远程的版本不一致，运行时会选择满足范围的那个版本，另一个直接复用。第三，宿主和远程的 shared 配置需要对齐，版本要求范围要有交集，否则会出现重复加载甚至加载失败。
运行时加载流程与 shared 协商机制
很多人配置完能跑起来，但对其内部机制一知半解，排查问题时就会很被动。Module Federation 的运行时核心是 webpack/container/reference 和 webpack/lib/share 这两组内部模块。当宿主执行到 import('app2/Button') 时，运行时首先检查 app2 容器是否已初始化，如果没有，就动态插入一个 script 标签去加载 remoteEntry.js。
remoteEntry.js 加载完成后，会在全局作用域挂载一个名为 app2 的容器对象，宿主调用它的 init 方法完成共享依赖的协商。协商的过程大致是：双方各自报出自己持有的 shared 依赖版本，按照 requiredVersion 的 semver 范围匹配，版本满足要求的一方提供模块，不满足或没有提供的一方则在运行时异步加载自己打包的那份兜底副本。协商完成后，宿主再调用 get('./Button') 拿到模块工厂函数，执行后得到真正的模块导出。
这个流程解释了几个常见现象：为什么远程组件加载前会先触发一次 init（这也是官方建议在入口处手动 await remote 的 init 的原因）；为什么 shared 依赖必须配置成异步边界（Webpack 会自动为 shared 模块创建 async chunk）；以及为什么版本不匹配时控制台会抛出 invalid version 警告但页面可能仍然正常——因为运行时找到了可用的替代版本。
落地时的典型坑点与适用边界
Module Federation 不是银弹，实际项目中踩坑最多的集中在几个方面。首先是循环依赖问题：如果宿主和远程互相引用对方的模块，初始化顺序处理不当会导致死锁或 undefined 导出，建议保持依赖方向单向，由统一的壳应用向下分发。其次是公共库的版本升级协同，singleton 模式下宿主升级了 React 大版本而远程没跟上，运行时行为会变得不可预测，团队之间需要有约定好的版本升级节奏。
另一个容易被忽视的点是 TypeScript 类型。远程模块在宿主里 import 时没有类型提示，因为类型信息不会随 remoteEntry.js 传递。常见解法是远程方额外发布一个类型包，宿主通过配置 paths 或使用 @module-federation/typescript 这类方案把运行时路径和编译时类型关联起来。此外，样式隔离、状态管理（Redux store 是否共享）、路由同步这些微前端的经典问题，Module Federation 本身并不处理，需要结合 qiankun、single-spa 或者自建方案补齐。
从适用边界来看，Module Federation 最适合的场景是：多个团队独立开发部署、需要细粒度共享组件或工具库、且技术栈统一在 Webpack 生态内的体系。如果只是想拆分一个单体应用的构建速度，用多进程构建或者 esbuild 可能更直接；如果是完全异构的技术栈混搭，容器化的微前端方案会更稳妥。把它当作运行时模块共享的基础设施来用，而不是完整的微前端框架，这个定位理解到位了，才能发挥它最大的价值。
Webpack 5Module Federation微前端修改时间：2026-09-05 08:32:36