微前端的本质是把一个大型前端应用拆分成多个可以独立开发、独立部署的子应用，再在运行时把它们组合成完整页面。早期的方案通常借助iframe或基于路由的single-spa、qiankun等工具，通过统一的生命周期和挂载机制来协调不同子应用。这些方案解决了团队协作和部署隔离的问题，但也带来了新的成本：子应用之间的资源不能高效共享，样式隔离、脚本隔离和公共依赖版本容易产生冲突，运行时加载性能也常常受到影响。JavaScript模块联邦（Module Federation）提供了一种更贴近运行时模块共享的思路，它让一个构建产物可以直接暴露模块给另一个构建产物使用，而不需要把代码打包进同一个文件。
Webpack 5将模块联邦作为内置能力引入后，微前端的集成方式发生了明显变化。远程应用可以只发布一个小的入口文件，宿主应用在运行时按需拉取远程模块，并且共享依赖可以通过声明式配置统一处理。接下来从核心原理、配置实践和常见问题三个角度展开。
一、模块联邦的核心机制
模块联邦并非简单地把两个应用的代码合并在一起，它建立了一套容器（container）与远程入口（remote entry）之间的运行时契约。使用ModuleFederationPlugin时，构建过程会生成若干容器文件，并记录哪些模块被暴露（exposes）以及哪些模块需要从远程获取（remotes）。宿主应用加载远程入口后，Webpack的运行时可以根据模块标识动态解析远程模块，整个过程像使用动态import加载本地代码一样。
与构建时共享依赖不同，模块联邦强调运行时共享。传统代码分割和公共依赖抽取通常发生在同一个构建上下文中，而模块联邦允许跨构建产物共享同一个依赖实例。例如，如果宿主应用和远程应用都依赖React，配置singleton后，运行时只会加载一个React副本，从而避免两个React实例导致的状态错乱。这是模块联邦适合微前端场景的重要原因。
二、远程应用与宿主应用的配置
要实现模块联邦集成，需要分别配置远程应用和宿主应用。远程应用负责暴露组件或函数，宿主应用负责声明远程地址并消费这些模块。下面是一个远程应用的Webpack配置，它把一个按钮组件和一个工具模块暴露给其他应用。
const { ModuleFederationPlugin } = require('webpack');
module.exports = {
output: {
publicPath: 'auto',
},
plugins: [
new ModuleFederationPlugin({
name: 'remoteApp',
filename: 'remoteEntry.js',
exposes: {
'./Button': './src/components/Button',
'./utils': './src/utils',
},
shared: {
react: { singleton: true, requiredVersion: '^18.2.0' },
'react-dom': { singleton: true, requiredVersion: '^18.2.0' },
},
}),
],
};
远程应用通常还会设置publicPath为auto，让入口文件的资源地址可以自动适配部署环境。filename参数指定远程入口文件名，默认是remoteEntry.js。exposes对象的键是其他应用引用该模块时的路径，值是当前构建中实际模块的文件位置。
宿主应用的配置则通过remotes字段声明远程应用的名称和入口地址。名称与地址之间用@分隔，地址指向远程应用部署后的入口文件。宿主应用不需要在构建时知道远程模块的具体内容，只需要在运行时从该地址加载容器。
const { ModuleFederationPlugin } = require('webpack');
module.exports = {
plugins: [
new ModuleFederationPlugin({
name: 'hostApp',
remotes: {
remoteApp: 'remoteApp@http://localhost:3001/remoteEntry.js',
},
shared: {
react: { singleton: true, requiredVersion: '^18.2.0' },
'react-dom': { singleton: true, requiredVersion: '^18.2.0' },
},
}),
],
};
完成配置后，宿主应用就可以在代码里通过动态import加载远程模块。模块路径的格式为远程应用名称/暴露路径，加载过程会被Webpack运行时拦截并转发到远程容器。
const RemoteButton = React.lazy(() => import('remoteApp/Button'));
function App() {
return (
<React.Suspense fallback={<div>加载中</div>}>
<RemoteButton />
</React.Suspense>
);
}
这种加载方式与普通的代码分割类似，远程模块可以单独异步加载，不影响宿主应用首屏。配合React.lazy或Vue的异步组件可以很方便地实现按需渲染。
三、共享依赖与版本策略
共享依赖是模块联邦方案中比较容易出错的部分。共享配置中的singleton表示整个运行时只允许存在一个该依赖的实例。当多个远程应用和宿主应用使用不同版本的React时，如果不做singleton，可能会同时加载多个版本，导致Hooks状态异常或Context失效。把React标记为singleton后，Webpack会根据版本范围选择加载一个满足要求的版本，但如果版本差距较大，依然可能出现不兼容。
requiredVersion用于声明当前应用期望的依赖版本范围，版本语义遵循npm的semver规则。Webpack在运行时检测到共享依赖版本不满足时，可能会加载应用自己的依赖副本，并给出警告。这种机制提供了灵活性，但也增加了调试难度。建议团队在微前端架构中统一核心依赖的大版本，例如所有子应用都使用React 18，避免运行时出现多版本共存。
对于非UI相关的工具库，例如日期处理、请求库等，可以不设置singleton，而让每个应用使用自己的副本。这样虽然会多加载一些代码，但可以减少版本冲突带来的运行时风险。对于需要全局唯一状态的库，如Redux store、主题对象等，则应当通过singleton配合手动共享实例，而不是完全依赖模块联邦的自动共享。
四、生产环境与常见问题
模块联邦的一个常见问题是部署路径配置错误。远程入口文件的地址必须通过浏览器能够直接访问，因此remotes字段中的地址要么使用绝对URL，要么在使用相对路径时正确设置publicPath。如果远程应用部署在子路径下，入口文件名和资源路径需要与Webpack的output.publicPath保持一致，否则宿主应用可能加载到错误的资源。
另一个常见问题是远程应用不可用时的降级处理。模块联邦本身不会自动提供错误兜底，宿主应用在使用远程模块时应当配合错误边界或动态加载失败的catch处理。例如在动态import的catch分支中渲染一个占位组件或提示信息，避免远程服务挂了导致整个页面白屏。
性能方面，远程入口文件通常较小，但首次加载远程模块时需要额外请求。可以通过预先加载远程入口、合理拆包以及使用HTTP/2多路复用来降低延迟。对于首屏必需的模块，不建议都通过模块联邦远程加载，而应将核心壳应用保持轻量，非核心功能按需从远程拉取。
实际项目中建议为远程模块建立版本清单和监控，防止远程应用发布不兼容版本后影响宿主应用。
此外，开发环境中的跨域问题也需要注意。远程入口地址通常与宿主应用不同源，需要确保远程服务允许跨域访问，或者通过网关将远程入口代理到同源路径。
五、总结
JavaScript模块联邦为微前端集成提供了一种比iframe和路由式挂载更灵活的运行时模块共享机制。它减少了公共依赖重复加载，允许不同团队独立部署，同时保持组件级或模块级的组合能力。但也要认识到，模块联邦不等于微前端的全部，还需要配合路由设计、样式隔离、错误处理和团队规范才能落地。
在实际选型时，如果团队已经使用Webpack 5并且微前端子应用技术栈基本一致，模块联邦是值得优先考虑的方案。如果子应用技术栈差异很大，或者对样式隔离和沙箱要求极高，仍然需要结合其他微前端容器方案。理解模块联邦的容器、暴露和共享依赖机制，是设计健壮微前端架构的关键。
模块联邦微前端JavaScript修改时间：2026-08-25 22:59:46