Webpack 5 引入的 Module Federation 让 JavaScript 应用可以在运行时从另一个构建产物中动态加载模块，而不需要在编译期确定依赖关系。它解决了多个独立部署项目之间共享组件、逻辑或整个页面的问题，尤其适合微前端架构。这一特性一经推出就受到社区热捧，目前已形成相对成熟的实践体系和工具生态。
理解 Module Federation 的核心：容器与共享
Module Federation 的本质是把每个构建产物视为一个容器（Container），容器可以暴露（expose）指定模块，也可以消费（consume）其他容器暴露的模块。构建时通过 ModuleFederationPlugin 配置 exposes 和 remotes 字段来声明这种关系。例如 host 应用想要使用远程 remote 应用提供的 Button 组件，只需要在 plugins 中声明 remote 的地址和名称，然后在代码中通过动态 import 来加载。
下面是一个典型的 host 与 remote 配置。host 端声明要使用的远程容器，remote 端声明对外暴露的模块以及入口文件名。这种运行时共享带来了巨大的灵活性，因为远程地址可以在运行时动态决定，甚至可以根据环境变量切换不同的 CDN 地址。
// host/webpack.config.js
const ModuleFederationPlugin = require('webpack/lib/container/ModuleFederationPlugin');
module.exports = {
plugins: [
new ModuleFederationPlugin({
name: 'host',
remotes: {
remoteApp: 'remote@http://localhost:3001/remoteEntry.js',
},
shared: ['react', 'react-dom'],
}),
],
};
// remote/webpack.config.js
const ModuleFederationPlugin = require('webpack/lib/container/ModuleFederationPlugin');
module.exports = {
plugins: [
new ModuleFederationPlugin({
name: 'remote',
filename: 'remoteEntry.js',
exposes: {
'./Button': './src/Button',
},
shared: ['react', 'react-dom'],
}),
],
};
共享依赖（shared）是模块联邦中最容易出问题的部分。如果不做任何配置，host 和 remote 都会各自打包一份 React，导致多个 React 实例共存，破坏 Hooks 和 Context 的状态一致性。正确的做法是声明 shared 数组，Webpack 会在运行时根据版本语义选择加载哪个版本，或者配置 singleton: true 强制使用单例。共享策略看似简单，实际涉及版本匹配、回退加载、异步初始化等复杂逻辑，社区也针对这个问题提出了不少方案。
模块联邦与微前端：多团队协作的落地实践
微前端的目标是让不同团队独立开发、独立部署、互不干扰，模块联邦天然适合作为微前端的实现基础。与 single-spa、qiankun 等基于 JavaScript 全局注册的方案不同，模块联邦允许更细粒度的模块共享，不仅仅是整个子应用，还支持组件级、工具函数级的复用。同时它不依赖任何框架，对 Vue、React、Angular 都能使用，只是在框架间的互操作上需要额外注意。
在实际落地中，模块联邦需要解决样式隔离、组件通信、路由协调等问题。样式隔离可以通过 CSS Modules、Shadow DOM 或者约定前缀来避免冲突；组件通信可以借助自定义事件、全局状态容器或者基于 props 的显式传递。一个常见的实践是：host 应用作为外壳，负责登录、导航、全局状态，各 remote 子应用通过联邦模块对外暴露自己的页面或功能组件，host 在运行时加载这些模块并渲染到对应的路由位置。
动态加载远程模块时还需要考虑加载失败的处理，比如远程服务不可用时的降级方案。社区通常会实现一个带超时和重试的加载函数，或者使用 Error Boundary 包裹远程组件，避免单个远程模块失败导致整个应用崩溃。另外，远程入口文件（remoteEntry.js）的缓存策略也很关键，需要确保发布新版本后客户端能及时获取到更新，同时又要利用 CDN 缓存降低加载延迟。
模块联邦社区：工具链与最佳实践
围绕模块联邦，社区已经涌现出许多实用工具。TypeScript 用户最头疼的是远程模块没有类型定义，@module-federation/typescript 和 Federated Types Plugin 可以自动生成远程模块的 .d.ts 文件，让开发者在 host 项目中获得完整的类型提示和编译期检查。对于 Next.js 用户，@module-federation/nextjs-mf 提供了对 SSR 和静态生成的支持，使 Next.js 应用也能作为 host 或 remote 参与联邦。
在服务端渲染场景下，模块联邦的挑战更大，因为 Node 环境和浏览器环境的模块加载机制不同。社区提出的解决方案包括使用 universal 渲染、将远程模块预打包到服务端 bundle、或者使用流式 SSR 配合动态导入。Node.js 环境下使用模块联邦通常需要借助 @module-federation/node 或自定义的加载器，以避免访问 window 等浏览器全局对象导致的错误。
部署策略方面，推荐将 remoteEntry.js 和暴露的模块文件发布到 CDN 上，并配置合理的缓存头。多个 remote 版本共存时，可以通过 semver 或自定义版本目录来实现 A/B 测试和灰度发布。一些团队还会将 remoteEntry.js 的地址写入环境变量或配置中心，使得 host 无需重新构建就可以切换远程服务的指向，大幅提升运维灵活性。
// 动态加载远程模块并处理降级
async function loadRemote(scope, module) {
try {
// 初始化远程容器
await __webpack_init_sharing__('default');
const container = window[scope];
await container.init(__webpack_share_scopes__.default);
const factory = await container.get(module);
return factory();
} catch (error) {
console.error(`Failed to load remote module ${scope}/${module}`, error);
// 返回降级组件或抛出错误
return { default: () => null };
}
}
// 使用方式
const RemoteButton = (await loadRemote('remoteApp', './Button')).default;
避坑指南：模块联邦常见问题与解决方案
共享依赖的版本冲突是最常遇到的问题之一。当 host 和 remote 使用不同主版本的 React 时，即使配置了 shared，也可能出现加载不兼容的版本。解决方案是尽量统一依赖主版本，并在 shared 中设置 requiredVersion 和 singleton。如果确实无法统一，可以通过动态导入时的 fallback 机制，或者使用 External 的方式让远程模块使用宿主提供的依赖实例。
CSS 样式在模块联邦中的隔离相对薄弱。由于远程组件的样式会被插入到全局作用域，容易造成样式污染。解决途径包括在远程组件内部使用 CSS Modules 或 styled-components 等方案，确保类名唯一；或者通过 shadow DOM 对每个子应用进行封装。对于需要共享设计系统的场景，推荐将基础样式通过联邦模块共享，子应用只编写业务样式，并遵循统一的命名规范。
另一个容易忽视的问题是远程模块中的相对路径资源（如图片、字体）。当远程模块被打包后，相对路径的引用会失效，因为最终加载时的上下文是 host 应用的页面。解决办法是在远程模块构建时使用 publicPath 配置为绝对 URL，或者将资源转换成 base64、使用 import 语句让 Webpack 处理。对于字体文件，也可以通过 CSS 中的 url() 配合绝对地址来避免路径错误。
最后提醒一点：模块联邦并不是银弹，它增加了应用间的耦合点和调试难度。在决定引入之前，要评估团队规模、项目独立性和部署节奏是否真的需要微前端级别的解耦。如果只是少数几个项目共享一些组件，使用 npm 私有包或 monorepo 可能是更简单可靠的选择。只有在需要独立部署、多团队并行开发且技术栈不统一的情况下，模块联邦才能发挥它最大的价值。
Webpack 5Module Federation微前端修改时间：2026-09-26 18:07:10