模块联邦（Module Federation）是Webpack 5引入的一项原生能力，它解决了微前端架构里最核心的一个问题：多个独立构建、独立部署的应用之间，如何在运行时共享和消费彼此的代码。传统的npm包共享方式要求所有应用统一升级版本，而模块联邦允许应用A在运行时动态加载应用B暴露出来的模块，还能让React、Vue这类公共依赖只保留一份实例，避免重复加载。本文将从原理、配置实战、方案对比三个层面，完整拆解基于模块联邦的微前端架构设计。
模块联邦的核心原理是什么
模块联邦围绕三个角色运作：host（消费方）、remote（提供方）和shared（共享依赖）。remote应用通过exposes配置把自己内部的某个组件暴露出去，host应用通过remotes配置声明要引用的远程应用，Webpack会在构建阶段生成一个异步加载器，真正加载动作发生在浏览器运行时。
这套机制的关键在于remote入口文件。构建时Webpack会为remote生成一个remoteEntry.js，它本质上是一个容器对象（Container），内部维护了暴露模块的映射表。host加载这个文件后，通过容器的get方法按需初始化具体的模块。由于整个流程基于动态import实现，所以模块粒度的懒加载是天然支持的，子应用的某个页面组件没被访问，它的chunk就不会被下载。
共享依赖的去重则更精妙。当host和remote都声明react为shared依赖时，运行时会有一个全局的共享注册表，先加载的一方会把React实例注册进去，后加载的一方发现版本满足要求（默认使用semver范围匹配），就直接复用已有实例，而不是再下载一份。这保证了单例场景下Context、事件系统不会出现两套副本的问题。
实战配置：主应用如何引用子应用组件
假设有一个主应用shell，需要消费子应用app1暴露的商品列表组件。子应用的webpack配置需要启用ModuleFederationPlugin，并通过exposes把组件挂出去：
// app1 的 webpack.config.js
const { ModuleFederationPlugin } = require('webpack').container;
const deps = require('./package.json').dependencies;
module.exports = {
plugins: [
new ModuleFederationPlugin({
name: 'app1',
filename: 'remoteEntry.js',
exposes: {
'./ProductList': './src/components/ProductList',
},
shared: {
react: { singleton: true, requiredVersion: deps.react },
'react-dom': { singleton: true, requiredVersion: deps['react-dom'] },
},
}),
],
};
注意singleton: true这个配置，它强制运行时只允许一份React实例存在。如果子应用和主应用的React大版本不一致且不满足版本范围，浏览器控制台会直接抛出警告甚至错误，这在联调阶段能快速暴露版本冲突问题，建议所有核心依赖都加上这个约束。
主应用侧的配置则通过remotes指向子应用的remoteEntry地址：
// 主应用 shell 的 webpack.config.js
const { ModuleFederationPlugin } = require('webpack').container;
module.exports = {
plugins: [
new ModuleFederationPlugin({
name: 'shell',
remotes: {
app1: 'app1@https://cdn.example-static.com/app1/remoteEntry.js',
},
shared: {
react: { singleton: true },
'react-dom': { singleton: true },
},
}),
],
};
配置完成后，业务代码里就可以像引用本地模块一样使用远程组件，写法上没有任何心智负担：
// 主应用业务代码
const ProductList = React.lazy(() => import('app1/ProductList'));
function App() {
return (
<Suspense fallback={<div>加载中...</div>}>
<ProductList />
</Suspense>
);
}
这里有个容易被忽略的细节：remoteEntry.js的地址建议配置成可动态注入的环境变量，而不是硬编码在构建产物里。因为子应用的部署域名、CDN路径在迁移或灰度时可能变化，主应用如果写死了地址，每次变更都要重新构建发布。一种常见做法是在index.html里通过window变量注入远程地址，运行时再拼装。
模块联邦与qiankun、iframe方案的对比
iframe是最早被用来做微前端的方式，隔离性最好，但缺陷也很明显：URL状态不同步、弹窗无法全屏、通信只能靠postMessage、每次加载都是完整页面白屏。它适合集成完全异构的老系统，比如把一个JSP系统嵌进新架构里，但作为主力微前端方案体验太差。
qiankun基于single-spa封装，主打应用级集成。子应用以完整应用的形式注册进来，qiankun负责JS沙箱隔离、CSS隔离和生命周期管理。它的优势是接入成本低、社区方案成熟、对子应用技术栈无侵入。但qiankun的共享依赖处理比较粗糙，多个React应用共存的场景下，如果不借助external等手段，每个子应用仍会各自打包一份框架代码，而且CSS隔离在某些场景下会失效。
模块联邦则是模块级的共享方案，粒度更细，公共依赖的复用由运行时注册表自动处理，天然比qiankun的依赖处理更优雅。下表总结了三者的核心差异：
| 维度 | iframe | qiankun | 模块联邦 |
|---|---|---|---|
| 集成粒度 | 页面级 | 应用级 | 模块级 |
| JS隔离 | 完全隔离 | 沙箱隔离 | 无隔离，靠约定 |
| 依赖共享 | 不支持 | 需手动配置 | 原生自动去重 |
| 通信方式 | postMessage | props/事件总线 | 直接函数调用 |
| 适用场景 | 异构老系统 | 完整子应用集成 | 团队间组件共享 |
模块联邦的短板在于没有沙箱机制。多个应用共享同一个window对象，全局变量污染、样式冲突都需要团队自己通过规范（比如CSS Modules、BEM命名约定）来约束。如果子应用来自不可控的外部团队，沙箱缺失会是安全隐患；但如果是同一公司内可控团队之间的协作，模块联邦的轻量和灵活反而是最大优势。
生产环境落地的工程化建议
第一点，remoteEntry的地址管理要走配置化。推荐搭建一个简单的服务发现服务，或者用低频更新的config.js来维护各子应用的最新地址，主应用启动时先拉取配置再动态注册remote。这样子应用发版时主应用完全不用重新构建，真正做到独立部署、独立发布。
第二点，共享依赖的版本治理要前置。建议在仓库里维护一份依赖版本清单，用CI检查各应用的shared依赖版本是否满足semver范围，版本漂移在合并阶段就拦住，而不是等到线上运行时报错。对于React这类单例依赖，务必显式声明requiredVersion，避免默认取到不兼容的版本。
// 动态注册远程应用的运行时方案
async function loadRemoteConfig() {
// 拉取配置中心下发的远程应用清单
const config = await fetch('https://cdn.ipipp.com/config/remotes.json').then(r => r.json());
window.__REMOTES__ = config; // 例如 { app1: 'app1@https://cdn.ipipp.com/app1/remoteEntry.js' }
}
第三点，做好加载失败的兜底。模块联邦的远程加载依赖网络，子应用服务故障时主应用不应该白屏。可以用React.lazy配合ErrorBoundary捕获加载异常，降级展示本地的兜底组件或者提示重试的交互。同时给remoteEntry请求加上超时控制，避免网络抖动时页面长时间卡在Suspense的fallback状态。
最后提一个高频踩坑点：开发环境下HMR（热更新）与模块联邦的组合偶尔会失效，表现为修改remote的代码后host侧不更新。排查思路是确认remoteEntry.js的地址指向的是devServer而非构建产物，并在devServer配置里加上允许跨域的头信息。Vite生态下也有对应的@originjs/vite-plugin-federation插件可以实现类似能力，但生产环境稳定性需要额外验证，如果是大型项目，目前Webpack 5的模块联邦仍然是最稳妥的选择。
微前端模块联邦Webpack Module Federation修改时间：2026-09-06 22:22:44