模块联邦（Module Federation）是 Webpack 5 引入的一项能力，它允许一个 JavaScript 应用在运行时从另一个独立构建的应用中动态加载模块。这个过程依赖 Web 网络完成远程入口脚本的请求、依赖版本协商和模块初始化。与传统的 npm 包共享方式不同，模块联邦不需要在构建阶段把共享代码打进本地产物，而是让浏览器在运行时像请求普通 Web 资源一样，从远端地址拉取对应模块。
为什么说它重塑了 Web 网络资源加载方式？过去部署两个前端应用，如果 A 应用要用 B 应用的一个组件，常见做法是把组件抽成 npm 包发布，A 应用安装后重新构建发布，或者用 iframe 做隔离。模块联邦改变了这个流程：A 应用只需要在配置里声明远程地址，运行时就会自动请求 B 应用的远程入口文件，然后按需获取组件代码。这种网络请求不是完整的页面跳转，而是脚本级别的按需加载，可以配合 HTTP 缓存、CDN 分发和共享依赖机制实现高效复用。
模块联邦的核心概念与配置模型
模块联邦把应用分成宿主（host）和远程（remote）两种角色。宿主负责加载远程模块，远程负责暴露模块。一个应用可以同时是宿主和远程。远程模块的暴露通过 exposes 字段声明，宿主的远程依赖通过 remotes 字段声明。例如一个用户中心应用暴露了用户信息卡片组件，主应用可以在运行时加载它。
下面这段配置展示了一个远程应用如何暴露模块。远程应用把自己的某个组件通过名称暴露给外部，同时指定生成独立的远程入口文件，这个文件会在运行时被宿主请求。
// 远程应用 webpack.config.js
const HtmlWebpackPlugin = require('html-webpack-plugin');
const { ModuleFederationPlugin } = require('webpack').container;
module.exports = {
entry: './src/index.js',
mode: 'development',
devServer: {
port: 3001,
},
plugins: [
new ModuleFederationPlugin({
name: 'userCenter',
filename: 'remoteEntry.js',
exposes: {
'./UserCard': './src/components/UserCard',
},
shared: {
react: { singleton: true },
'react-dom': { singleton: true },
},
}),
new HtmlWebpackPlugin({
template: './public/index.html',
}),
],
};
远程应用会生成一个名为 remoteEntry.js 的文件，里面记录了模块映射和加载逻辑。宿主应用通过 remotes 字段声明远程地址，通常写成 userCenter@http://localhost:3001/remoteEntry.js 的形式。地址中的协议、域名和端口就是 Web 网络请求的目标。
// 宿主应用 webpack.config.js
const { ModuleFederationPlugin } = require('webpack').container;
module.exports = {
entry: './src/index.js',
mode: 'development',
devServer: {
port: 3000,
},
plugins: [
new ModuleFederationPlugin({
name: 'mainApp',
remotes: {
userCenter: 'userCenter@http://localhost:3001/remoteEntry.js',
},
shared: {
react: { singleton: true },
'react-dom': { singleton: true },
},
}),
],
};
在业务代码中，宿主可以像使用本地模块一样导入远程组件。Webpack 会在构建时识别这个导入，生成运行时加载逻辑。真正执行时，浏览器会先请求 remoteEntry.js，获取远程模块的元数据，再按需请求组件对应的 chunk 文件。
远程模块如何通过 Web 网络加载
模块联邦的运行时加载过程本质上就是 Web 网络请求的编排。当宿主代码执行到远程模块导入时，Webpack 运行时会动态创建一个 script 标签，把远程入口脚本地址插入到页面中。这个脚本加载完成后，会在全局对象上注册远程应用的模块容器。之后宿主再通过容器获取具体的模块工厂函数。
远程入口脚本本身是一个很小的引导文件，其中不会包含全部业务代码。它负责告诉宿主远程模块的 chunk 映射关系。真正的组件代码仍然以独立 chunk 文件存在于远程服务器上，只有在实际使用时才会被请求。这种设计使得网络请求可以按需发生，避免一次性拉取所有远程资源。
共享依赖的版本协商也是通过网络加载的重要环节。如果宿主和远程都声明了 react 作为共享依赖，运行时不会简单地从远程下载一份重复的 React。它会检查宿主环境中是否已经存在兼容版本，如果存在则直接复用，如果不存在才通过 Web 网络请求远程提供的共享模块。通过 singleton: true 可以强制全局只保留一个实例，避免多个 React 副本导致的状态丢失问题。
// 共享依赖配置示例
shared: {
react: {
singleton: true,
eager: false,
requiredVersion: '^18.0.0',
},
'react-dom': {
singleton: true,
eager: false,
requiredVersion: '^18.0.0',
},
}
当共享依赖需要从远端获取时，Webpack 会根据远程入口中的模块信息构造网络请求。这个请求通常指向远程应用的 chunk 文件地址。如果远程应用部署在 CDN 上，请求会直接命中边缘节点，减少延迟。为了提升性能，可以让远程入口文件和 chunk 文件都设置长缓存，同时利用 contenthash 保证内容更新时 URL 发生变化。
生产环境下的网络部署与优化
模块联邦在本地开发时使用 localhost 就能跑通，但生产环境需要考虑 CDN、跨域、缓存和版本更新等问题。远程入口地址通常会配置为 CDN 域名，例如 https://cdn.ipipp.com/userCenter/remoteEntry.js。此时必须保证远程服务器返回正确的 CORS 响应头，否则浏览器会阻止跨域脚本读取模块容器信息。
如果远程应用和宿主应用部署在不同域名下，远程服务器的响应头中需要包含 Access-Control-Allow-Origin。对于 Webpack 的开发服务器，可以通过 devServer.headers 配置跨域头。对于生产环境的静态服务器，通常在 Nginx 或对象存储中设置同源策略。下面是一个开发服务器的配置示例。
// 远程应用 devServer 配置跨域
devServer: {
port: 3001,
headers: {
'Access-Control-Allow-Origin': '*',
},
}
缓存策略是生产部署中的重点。远程入口文件 remoteEntry.js 体积小、变化频率低，但一旦远程应用重新构建，入口文件的内容哈希可能变化。如果对它设置过长的强缓存，宿主可能无法及时获取最新模块映射。常见的做法是让 remoteEntry.js 使用协商缓存或较短的强缓存，而业务 chunk 文件使用 contenthash 配合一年的强缓存。这样既能保证更新及时，又能最大化缓存命中率。
版本更新还涉及远程模块的兼容性。当远程应用升级了某个共享依赖的大版本，宿主如果没有同步升级，运行时协商可能失败。为了避免线上事故，可以在远程入口地址中加入版本号或哈希，例如 remoteEntry.js?v=2.1.0。这相当于给远程模块加了版本标识，宿主可以根据需要升级远程地址。虽然 URL 中的查询参数不能直接替代缓存策略，但它提供了一种简单的版本隔离手段。
另一个容易被忽略的是 HTTP/2 的影响。模块联邦在加载远程模块时可能触发多个并发请求，包括远程入口、业务 chunk、共享依赖 chunk 等。在 HTTP/1.1 下，浏览器对同域名的并发连接数有限制，过多请求会排队。使用 HTTP/2 可以让这些请求在单连接上多路复用，显著降低远程模块的加载时间。因此建议生产环境的 CDN 或静态服务器开启 HTTP/2。
模块联邦与传统网络加载方案的对比
理解模块联邦的价值，需要把它和传统方案放在一起看。常见的远程代码加载方式有三种：全局脚本引入、JSONP 动态加载、ESM 原生模块导入。全局脚本引入依赖全局变量命名空间，容易冲突；JSONP 动态加载通常用于单应用的代码分割，无法跨应用共享模块；ESM 原生模块导入虽然标准化，但浏览器兼容性和构建工具链支持仍在演进。
模块联邦综合了这些方案的优点。它在运行时动态创建 script 标签，类似 JSONP 的加载方式，但增加了模块容器协议，可以处理依赖共享和版本协商。它不像 ESM 那样受限于浏览器原生支持，而是通过 Webpack 运行时兼容更广泛的环境。对于微前端架构来说，这种能力让多个独立部署的应用可以像单体应用一样互相引用模块，而不用引入额外的全局状态或通信协议。
当然，模块联邦并不是银弹。它也带来了网络请求数量的增加、远程入口的额外加载成本、以及跨域和安全配置的复杂度。当共享模块体积较小且依赖稳定时，传统的 npm 包发布可能仍然更简单。但当团队需要在多个应用间实时共享组件、避免重复构建和发布时，模块联邦通过 Web 网络实现的运行时共享优势就非常明显。
在实际项目中，可以把模块联邦与 CDN、HTTP 缓存、CORS、共享依赖版本管理结合起来，构建一套以 Web 网络为通道的模块分发体系。远程应用只负责暴露模块并部署静态资源，宿主应用按需加载，双方独立迭代、独立发布。这种模式下，前端架构从构建期耦合走向了运行期协作，Web 网络不再只是传输 HTML 和接口数据的管道，而是变成了模块交换的核心基础设施。