什么是模块联邦?（Module Federation）

一、前端模块共享的传统困境

在大型前端项目或多应用协作场景中，"模块共享" 是绕不开的需求 ------ 比如多个应用复用同一套按钮组件、工具函数，或不同团队协作开发时共享基础模块。但在模块联邦（Module Federation）出现前，传统方案始终存在难以解决的痛点：

1. npm 包共享：迭代效率低下

将公共组件打包成 npm 包是最常见的方式，但流程繁琐：修改组件后需重新发布版本，所有依赖该包的应用都要手动更新依赖、重新构建部署。对于频繁迭代的内部组件库，这种 "发布 - 安装 - 重构" 的循环严重拖慢开发效率，且容易出现 "版本不一致导致的兼容问题"。

2. CDN 直接引入：粗糙且易出问题

为了跳过 npm 发布流程，部分团队会将组件打包成 umd 格式丢到 CDN，消费方通过

依赖需手动管理：如果共享组件依赖 React、Vue 等库，消费方必须手动引入对应版本，否则会出现 "模块未定义" 的运行时错误；

全局变量污染：umd 包通常挂载到 window 上，多个模块可能出现命名冲突；

无法按需加载：

无版本控制：CDN 资源更新后，需手动处理缓存或版本号，容易出现 "旧版本缓存导致的功能异常"。

3. 早期微前端：耦合度高，共享粒度粗

早期微前端方案（如 qiankun）更侧重 "应用级嵌入"------ 将多个独立应用整合成一个整体，但跨应用共享组件 / 模块时需额外适配（如通过自定义事件传递状态），集成成本高，且共享粒度仅停留在 "整个应用"，无法实现细粒度的组件 / 工具函数共享。

这些痛点的核心矛盾的是：传统方案无法在 "高效迭代""按需加载""依赖自动管理" 之间找到平衡，而模块联邦的出现，正是为了解决这一核心矛盾。

二、模块联邦：前端模块共享的终极方案

模块联邦（Module Federation，简称 MF）是 Webpack 5 推出的核心特性，其核心目标是：打破应用边界，让多个独立构建的前端应用，像使用本地模块一样按需共享组件、工具函数，且无需手动处理依赖和部署流程。

简单来说，它就像一个 "前端模块的共享枢纽"------ 每个应用都可以作为 "模块提供者"（暴露自身模块）或 "模块消费者"（加载其他应用的模块），甚至两者兼具，形成灵活的模块共享生态。

三、模块联邦的核心原理（结合通俗理解）

很多人第一次接触模块联邦时，会有这样的直观认知："是不是把共享组件放到 CDN 上，消费方通过 Webpack 识别 import 语句，再请求 CDN 资源并注入使用？"------ 这个理解方向完全正确，我们可以基于这个认知，拆解其底层原理：

核心原理一句话总结

模块联邦本质是：将共享模块（带依赖元信息）部署到远程服务器（如 CDN），Webpack 通过 "编译时标记 + 运行时加载"，让消费方用原生 import 语法加载远程模块；当代码执行到该 import 时，自动请求远程资源，经格式适配和依赖处理后，注入宿主应用的模块系统，实现 "本地使用" 的体验。

原理拆解（分 4 步）

1. 模块提供者：打包 "带元信息的共享模块"

模块提供者（称为 Remote 应用）打包时，Webpack 会做两件关键事：

生成 remoteEntry.js：这不是模块本身，而是 "模块导航文件"------ 包含模块清单（暴露了哪些模块、模块的真实地址）、依赖元信息（模块依赖的库如 React/Vue）、加载器函数（用于后续解析模块）；

拆分模块 chunk：将暴露的组件 / 工具函数拆成独立的 JS chunk（如 Button 组件对应 123.js），并部署到 CDN 或远程服务器。

这里的关键是：共享的不是 "裸模块"，而是 "带依赖元信息的模块单元" ，避免了传统 CDN 引入时 "依赖手动管理" 的问题。

2. 模块消费者：编译时标记远程模块

模块消费者（称为 Host 应用）配置 Webpack 时，会声明要加载的远程应用（如 app2: 'app2@cdn.example.com/remoteEntry...'）。Webpack 编译时会识别这类远程模块的 import 语句（如 import 'app2/Button'），并做 "标记"------ 告诉运行时："这个模块不是本地的，需要从远程加载"。

这一步就像你理解的 "Webpack 的 switch 功能"：编译时给远程模块打标签，运行时遇到标签就切换到 "远程加载逻辑"，而非本地模块的 "文件读取逻辑"。

3. 运行时：异步请求远程资源（非简单 script 插入）

当宿主应用运行到远程模块的 import 语句时，会触发以下流程：

第一步：加载 remoteEntry.js：通过 Webpack 内置的异步加载逻辑（而非直接插入

第二步：解析模块地址：remoteEntry.js 执行后，通过其内置的模块清单，找到目标模块（如 app2/Button）对应的真实 CDN 地址（如 cdn.example.com/123.js）；

第三步：加载目标模块：通过 Webpack 封装的异步加载函数（如 webpack_require.e）请求目标模块的 JS chunk，这一步同样不是简单插入

4. 注入使用：依赖自动处理 + 格式适配

目标模块加载完成后，Webpack 会做最后两件事：

依赖自动复用：如果远程模块依赖的库（如 React），宿主应用已加载，则直接复用，避免重复打包；若未加载，则自动加载共享依赖（通过 shared 配置控制）；

格式适配与注入：将远程模块的代码格式，转换成宿主应用能识别的模块格式（避免全局污染），并注入宿主的模块系统 ------ 此时，远程模块就像本地模块一样，可直接使用。

与 "简单 CDN 引入" 的核心区别

对比维度	简单 CDN 引入（umd 包）	模块联邦
依赖管理	手动引入，易冲突	自动识别依赖，共享复用
加载方式	插入	异步请求 Webpack 格式 chunk，无全局污染
按需加载	不支持，同步加载	支持，用到才加载
版本控制	需手动管理版本号 / 缓存	通过 shared 配置控制版本兼容
使用体验	需从 window 取模块，体验割裂	原生 import 语法，和本地模块一致

四、模块联邦的实际使用方法（React 示例）

下面用两个应用演示核心用法：app1（宿主应用，加载远程模块）和 app2（远程应用，暴露共享组件）。

前置条件

构建工具：Webpack 5+（仅 Webpack 5 原生支持模块联邦）；

技术栈：React（Vue 用法类似，核心配置一致）。

1. 远程应用（app2：模块提供者）

步骤 1：配置 Webpack（webpack.config.js）

javascript 复制代码

const { ModuleFederationPlugin } = require('webpack').container;
const HtmlWebpackPlugin = require('html-webpack-plugin');
module.exports = {
  mode: 'development',
  devServer: { port: 3002 }, // 远程应用运行端口
  output: {
    uniqueName: 'app2', // 远程应用唯一标识（避免冲突）
  },
  plugins: [
    new ModuleFederationPlugin({
      name: 'app2', // 远程应用名称（宿主需通过该名称引用）
      filename: 'remoteEntry.js', // 模块导航文件（必须叫这个名字）
      exposes: {
        // 暴露的模块：key 是宿主引用的路径，value 是本地模块路径
        './Button': './src/Button', // 暴露 Button 组件
        './utils': './src/utils', // 暴露工具函数
      },
      // 共享依赖：避免 React/ReactDOM 重复打包
      shared: {
        react: { singleton: true, eager: true }, // singleton：单例模式；eager：优先加载
        'react-dom': { singleton: true, eager: true },
      },
    }),
    new HtmlWebpackPlugin({ template: './public/index.html' }),
  ],
};

步骤 2：编写共享模块

创建 src/Button.jsx（共享组件）：

javascript 复制代码

export default function App2Button() {
  return <button style={{ color: 'red', fontSize: '20px' }}>我是 app2 的共享按钮</button>;
}

步骤 3：启动远程应用

运行 npm run dev，远程应用会启动在 http://localhost:3002，此时可通过 http://localhost:3002/remoteEntry.js 访问导航文件。

2. 宿主应用（app1：模块消费者）

步骤 1：配置 Webpack（webpack.config.js）

javascript 复制代码

const { ModuleFederationPlugin } = require('webpack').container;
const HtmlWebpackPlugin = require('html-webpack-plugin');
module.exports = {
  mode: 'development',
  devServer: { port: 3001 }, // 宿主应用运行端口
  plugins: [
    new ModuleFederationPlugin({
      name: 'app1', // 宿主应用名称（仅用于标识）
      // 配置要加载的远程应用：key 是远程应用名称，value 是 "远程名称@导航文件地址"
      remotes: {
        app2: 'app2@http://localhost:3002/remoteEntry.js',
      },
      // 共享依赖：和远程应用保持一致，避免重复打包
      shared: {
        react: { singleton: true, eager: true },
        'react-dom': { singleton: true, eager: true },
      },
    }),
    new HtmlWebpackPlugin({ template: './public/index.html' }),
  ],
};

步骤 2：使用远程模块

创建 src/App.jsx，用原生 import 语法加载远程模块：

javascript 复制代码

import React, { lazy, Suspense } from 'react';
// 按需加载远程模块（推荐）：用 lazy + Suspense 处理加载状态
const App2Button = lazy(() => import('app2/Button')); // 格式：远程应用名称/暴露的模块 key
const App2Utils = lazy(() => import('app2/utils'));
function App() {
  return (
    <div style={{ padding: '20px' }}>
      <h1>我是宿主应用（app1）</h1>
      {/* 远程模块加载时显示 fallback */}
      <Suspense fallback="加载中...">
        <App2Button />
      </Suspense>
    </div>
  );
}
export default App;

步骤 3：启动宿主应用

运行 npm run dev，访问 http://localhost:3001，即可看到来自 app2 的红色按钮 ------ 此时，宿主应用已成功加载并使用远程模块，且完全感知不到 "这是远程资源"。

五、模块联邦的核心特性与适用场景

核心特性

独立部署：宿主和远程应用可各自独立开发、构建、部署，修改远程模块后无需重构宿主；

双向共享：一个应用既可以是宿主（加载模块），也可以是远程（暴露模块）；

依赖去重：共享依赖自动复用，避免重复打包，减小包体积；

按需加载：远程模块仅在使用时才加载，优化首屏性能。

适用场景

微前端架构：实现细粒度的组件 / 模块共享，替代传统粗粒度的应用嵌入；

大型应用拆分：将巨型应用拆分为多个独立构建的子应用（如首页、订单页），各自迭代；

内部组件库共享：无需发布 npm 包，多个应用实时使用最新版公共组件；

跨团队协作：不同团队维护不同子应用，通过模块联邦无缝集成，降低协作成本。

六、使用注意事项

依赖版本兼容：共享依赖（如 React）需保证版本兼容，可通过 requiredVersion 配置限制版本；

构建工具限制：仅 Webpack 5+ 原生支持，Vite 需用 vite-plugin-federation 插件，Rollup 支持有限；

缓存与降级：给 remoteEntry.js 和模块 chunk 加哈希值（如 remoteEntry.[hash].js），避免缓存问题；同时需做好降级方案（如远程应用挂掉时，显示本地备用组件）；

样式隔离：共享组件的样式需避免污染宿主，可使用 CSS Modules、Shadow DOM 等方案。

总结

模块联邦的核心价值，是让前端模块共享从 "繁琐的手动管理" 走向 "自动化、按需化、低耦合"。它没有改变开发者的使用习惯（仍用 import 语法），却解决了传统方案的核心痛点，让大型前端项目的拆分与协作变得更高效。

如果你正在面临 "多应用共享组件""大型项目拆分" 等问题，模块联邦无疑是当前最理想的解决方案 ------ 它不仅是一种技术，更是一种 "前端架构的设计思想"：打破边界，让模块自由流动。