前端模块联邦介绍

前端的模块联邦（Module Federation） 是 Webpack 5 引入的一项革命性功能，它允许在多个独立构建的 JavaScript 应用之间动态共享和加载代码 ，而无需将它们打包到同一个 bundle 中。这项技术特别适用于微前端架构（Micro Frontends） ，使得多个团队可以独立开发、部署各自的前端应用，并在运行时按需集成。

一、核心概念

1. 什么是模块联邦？

模块联邦是一种 "分布式模块系统" ，它让一个应用（称为 host ）可以在运行时从另一个远程应用（称为 remote）动态加载模块（如组件、函数、库等），就像这些模块是本地的一样。

2. 关键术语

Host（宿主） ：消费远程模块的应用。
Remote（远程） ：暴露模块供其他应用使用。
Shared（共享依赖） ：多个应用之间共享的第三方依赖（如 React、Lodash），避免重复加载。
Federated Module（联邦模块） ：通过模块联邦机制暴露或消费的模块。

二、工作原理

模块联邦的核心在于 Webpack 在构建时生成特殊的入口文件（remoteEntry.js） ，该文件描述了可被远程使用的模块列表及其加载方式。

构建流程简述：

Remote 应用构建时，通过 ModuleFederationPlugin 暴露模块，并生成 remoteEntry.js。
Host 应用在构建时知道 remote 的地址（URL），但不会打包 remote 的代码。
运行时，Host 动态加载 remoteEntry.js，然后按需加载具体模块。
Shared 依赖通过语义化版本匹配（如 ^18.0.0）确保只加载一份，避免冲突。

三、配置示例

Webpack 5

一、Remote 应用（暴露模块）

js 复制代码

// webpack.config.js (Remote)
const ModuleFederationPlugin = require('webpack/lib/container/ModuleFederationPlugin');

module.exports = {
  plugins: [
    new ModuleFederationPlugin({
      name: 'remoteApp',
      filename: 'remoteEntry.js',
      exposes: {
        './Button': './src/components/Button.jsx',
        './utils': './src/utils/index.js'
      },
      shared: {
        react: { singleton: true, requiredVersion: '^18.0.0' },
        'react-dom': { singleton: true, requiredVersion: '^18.0.0' }
      }
    })
  ]
};

二、Host 应用（消费模块）

js 复制代码

// webpack.config.js (Host)
const ModuleFederationPlugin = require('webpack/lib/container/ModuleFederationPlugin');

module.exports = {
  plugins: [
    new ModuleFederationPlugin({
      name: 'hostApp',
      remotes: {
        remoteApp: 'remoteApp@http://localhost:3001/remoteEntry.js'
      },
      shared: {
        react: { singleton: true, requiredVersion: '^18.0.0' },
        'react-dom': { singleton: true, requiredVersion: '^18.0.0' }
      }
    })
  ]
};

在 Host 中使用 Remote 模块

jsx 复制代码

// App.jsx (Host)
import React, { lazy, Suspense } from 'react';

// 动态导入远程模块
const RemoteButton = lazy(() => import('remoteApp/Button'));

function App() {
  return (
    <div>
      <h1>Host App</h1>
      <Suspense fallback="Loading...">
        <RemoteButton />
      </Suspense>
    </div>
  );
}

export default App;

Rsbuild

✅ 前提：安装工具

bash 复制代码

npm create module-federation@latest
# 或
pnpm create module-federation@latest

选择模板时：

Remote → 选 provider-rsbuild
Host → 选 consumer-rsbuild

一、Remote 应用（Provider）配置

目录结构（简化）

text 复制代码

remote-app/
├── src/
│   └── Button.tsx
├── rsbuild.config.ts
└── package.json

1. `src/Button.tsx`

tsx 复制代码

// remote-app/src/Button.tsx
export default function Button() {
  return <button style={{ padding: '8px 16px', background: '#007bff', color: 'white' }}>
    Remote Button from Provider
  </button>;
}

2. `rsbuild.config.ts`（关键：暴露模块）

ts 复制代码

import { defineConfig } from '@rsbuild/core';
import { pluginReact } from '@rsbuild/plugin-react';
import { pluginModuleFederation } from '@module-federation/rsbuild-plugin';

export default defineConfig({
  plugins: [
    pluginReact(),
    pluginModuleFederation({
      name: 'remoteApp',
      filename: 'remoteEntry.js',
      exposes: {
        './Button': './src/Button.tsx',
      },
      shared: {
        react: { singleton: true, requiredVersion: '^18.0.0' },
        'react-dom': { singleton: true, requiredVersion: '^18.0.0' },
      },
    }),
  ],
  server: {
    port: 3001, // Remote 运行在 3001
  },
});

💡 pluginModuleFederation 是 Rsbuild 官方提供的模块联邦插件。

3. 启动 Remote

bash 复制代码

npm run dev
# 访问 http://localhost:3001/remoteEntry.js 确认可访问

二、Host 应用（Consumer）配置

目录结构

text 复制代码

host-app/
├── src/
│   └── App.tsx
├── rsbuild.config.ts
└── package.json

1. `src/App.tsx`

tsx 复制代码

// host-app/src/App.tsx
import React, { Suspense, lazy } from 'react';

// 动态导入远程模块
const RemoteButton = lazy(() => import('remoteApp/Button'));

export default function App() {
  return (
    <div>
      <h1>Host App</h1>
      <Suspense fallback="Loading button...">
        <RemoteButton />
      </Suspense>
    </div>
  );
}

2. `rsbuild.config.ts`（关键：声明 remotes）

ts 复制代码

import { defineConfig } from '@rsbuild/core';
import { pluginReact } from '@rsbuild/plugin-react';
import { pluginModuleFederation } from '@module-federation/rsbuild-plugin';

export default defineConfig({
  plugins: [
    pluginReact(),
    pluginModuleFederation({
      name: 'hostApp',
      remotes: {
        remoteApp: 'remoteApp@http://localhost:3001/remoteEntry.js',
      },
      shared: {
        react: { singleton: true, requiredVersion: '^18.0.0' },
        'react-dom': { singleton: true, requiredVersion: '^18.0.0' },
      },
    }),
  ],
  server: {
    port: 3000, // Host 运行在 3000
  },
});

⚠️ 注意：remotes 中的 remoteApp 名称必须和 Remote 的 name 一致。

3. 启动 Host

bash 复制代码

npm run dev
# 访问 http://localhost:3000
# 应该能看到 "Remote Button from Provider"

四、优势

优势	说明
独立部署	各子应用可独立开发、测试、部署，互不影响。
按需加载	只在需要时加载远程模块，减少初始包体积。
依赖共享	避免多个应用重复加载相同库（如 React），节省带宽和内存。
技术栈无关（部分）	虽然通常用于同技术栈（如 React），但也可封装为通用组件实现跨框架集成。
无构建耦合	Host 和 Remote 完全解耦，无需共享代码库或 monorepo。

五、常见使用场景

微前端架构：大型产品拆分为多个子应用（如商品、订单、用户中心），由不同团队维护。
组件库即服务：将通用 UI 组件（如按钮、表单）部署为远程模块，供多个项目使用。
A/B 测试或灰度发布：动态加载不同版本的模块进行实验。
跨团队协作：前端团队 A 开发主应用，团队 B 开发某个功能模块，通过模块联邦集成。

六、注意事项与挑战

版本兼容性：Shared 依赖的版本必须协调一致，否则可能出错。
网络延迟：远程模块加载依赖网络，需处理加载失败和 fallback。
调试复杂度：错误堆栈可能跨越多个应用，调试难度增加。
CORS 问题：远程资源需配置正确的 CORS 策略。
缓存策略 ：remoteEntry.js 和模块文件需合理设置缓存，避免更新不及时。

七、与其他微前端方案对比

方案	模块联邦	Single-SPA	iframe	Web Components
构建集成	✅ Webpack 原生支持	❌ 需手动管理生命周期	❌ 完全隔离	⚠️ 需自定义元素
样式隔离	❌ 需额外处理	❌	✅	✅（Shadow DOM）
依赖共享	✅ 内置支持	❌	❌	❌
学习成本	中	中	低	高
性能	高（按需加载）	中	低（重复加载）	中

八、未来展望

Vite 支持 ：社区已出现类似插件（如 vite-plugin-federation），但生态不如 Webpack 成熟。
标准化：模块联邦推动了"运行时模块共享"理念，可能影响未来前端架构标准。
工具链完善：DevTools、错误监控、性能分析等配套工具正在逐步完善。

九、实际项目改造

1、改造前的关键准备工作

✅ 1. 明确改造目标

是为了 独立部署 ？还是 组件复用 ？或是 团队解耦？
哪些项目做 Host（主应用） ？哪些做 Remote（子应用/功能模块） ？
是否所有项目都用相同技术栈（如 React 18）？如果不是，是否需要封装兼容层？

✅ 2. 统一基础依赖版本

模块联邦对共享依赖（如 React、ReactDOM、Lodash）非常敏感。

所有项目应尽量使用 相同主版本（如 React 18.x）
在 shared 配置中启用 singleton: true，避免多实例冲突

⚠️ 如果 A 项目用 React 17，B 用 React 18，直接共享会崩溃！

✅ 3. 评估项目结构

是否是单页应用（SPA）？多页应用（MPA）改造成本更高
是否重度依赖全局状态（如 Redux、Zustand）？需设计跨应用状态通信方案
样式是否全局污染？需考虑 CSS 隔离（后面详述）

2、改造过程中必须注意的事项

🔒 1. 共享依赖（Shared Dependencies）配置要精准

js 复制代码

shared: {
  react: { singleton: true, requiredVersion: '^18.0.0' },
  'react-dom': { singleton: true, requiredVersion: '^18.0.0' },
  lodash: { version: '4.17.21' } // 非 singleton 也可，但建议统一
}

必须开启 singleton: true：确保 React 等库只加载一次
requiredVersion 要匹配：Host 和 Remote 的版本范围需兼容

🌐 2. 远程入口地址（remoteEntry.js）管理

开发环境：http://localhost:3001/remoteEntry.js

生产环境：应通过 环境变量或配置中心 动态注入，避免硬编码

js 复制代码

// rsbuild.config.ts
const remoteUrl = process.env.REMOTE_BUTTON_URL || 'http://localhost:3001';
remotes: {
  buttonLib: `buttonLib@${remoteUrl}/remoteEntry.js`
}

🧱 3. 路由协调（如果涉及页面级微前端）

Host 通常持有主路由（如 React Router）
Remote 不应再创建自己的 <BrowserRouter>，否则会冲突
推荐 Remote 只暴露组件，由 Host 控制路由和布局

❌ 错误做法：Remote 里写 <BrowserRouter><Routes>...</Routes></BrowserRouter>

✅ 正确做法：Remote 导出一个 <ProductList /> 组件，Host 在 /products 路由下渲染它

🎨 4. 样式隔离与冲突处理

模块联邦 不自动隔离 CSS，容易出现：

全局样式覆盖（如 .btn { color: red } 影响所有按钮）
CSS-in-JS 或 Tailwind 类名冲突

解决方案：

使用 CSS Modules 或 Scoped CSS（Vue）
组件库加统一前缀（如 .mf-button）
考虑使用 Shadow DOM（Web Components 封装）
或在构建时通过 PostCSS 插件自动加命名空间

📦 5. 资产路径（静态资源）问题

Remote 中的图片、字体等资源路径在 Host 中可能 404。

解决方法：

所有静态资源走 CDN 绝对路径

或配置 Remote 的 publicPath 为完整 URL：

js 复制代码

// Remote 的 rsbuild.config.ts
output: {
  assetPrefix: 'http://localhost:3001/' // 或生产 CDN 地址
}

3、改造中常见的难点与解决方案

难点	原因	解决方案
React 多实例错误（Invalid Hook Call）	Host 和 Remote 各自打包了 React	✅ `shared` 中设置 `singleton: true` + 统一版本
远程模块加载失败 / 404	`remoteEntry.js` 路径错误或未启动 Remote	✅ 先启 Remote，检查 Network 面板是否加载成功
样式互相污染	全局 CSS 无隔离	✅ 使用 CSS Modules / BEM 命名规范 / Shadow DOM
状态无法共享	每个应用有自己的 Redux store	✅ 通过 props 传递，或使用全局事件总线、自定义 Hooks、 Zustand + 共享 Store 实例
本地开发体验差	需同时启动多个服务	✅ 使用 `concurrently` 或 `turbo` 并行启动： `"dev": "concurrently "rsbuild dev --port 3000" "rsbuild dev --port 3001""`
TypeScript 类型缺失	Host 无法知道 Remote 模块的类型	✅ 方案1：共享 `d.ts` 文件方案2：Remote 发布类型包方案3：Host 中手动声明 `declare module 'remoteApp/Button'`
生产环境缓存问题	`remoteEntry.js` 被浏览器缓存，更新不生效	✅ 文件名加 hash（如 `remoteEntry.[hash].js`） ✅ 或通过查询参数加版本号：`?v=1.2.3`

4、推荐改造步骤（渐进式）

不要一次性重构所有项目！建议：

选一个非核心模块试点（如"用户头像组件"）
将其改造成 Remote，暴露一个简单组件
在 Host 中消费它，验证流程
逐步迁移更多模块
最后处理主应用（Host）的路由和布局集成

5、工具链建议

工具	作用
`@module-federation/rsbuild-plugin`	Rsbuild 官方模块联邦插件
`concurrently`	并行启动多个 dev server
`vite-plugin-federation`（如用 Vite）	Vite 的模块联邦方案（生态较新）
`webpack-bundle-analyzer`	分析 bundle，确认 React 是否被重复打包
自定义 ESLint 规则	禁止在 Remote 中使用 `BrowserRouter` 等危险操作

6、总结：成功改造的关键

✅ 统一技术栈版本（尤其是 React）
✅ 精准配置 shared 依赖
✅ Remote 只暴露组件，不掌控路由
✅ 做好样式隔离和资源路径处理
✅ 渐进式改造，先小后大

模块联邦不是银弹，但它能极大提升大型前端项目的可维护性和团队协作效率。只要规划得当，改造过程虽然有挑战，但收益非常显著。

总结

模块联邦是现代前端工程化的重要突破，它解决了微前端中代码复用、独立部署、依赖共享等核心痛点。虽然有一定学习曲线和运维复杂度，但在大型项目或多团队协作场景下，其价值非常显著。如果你正在构建一个需要高度解耦、灵活扩展的前端系统，模块联邦值得深入研究和实践。

直通车

webpack.js.org/concepts/mo... ---- webpack

module-federation.io/zh/guide/st... ---- module-federation.io

rsbuild.rs/zh/guide/ad... ---- Rsbuild

前端模块联邦介绍

一、核心概念

1. 什么是模块联邦？

2. 关键术语

二、工作原理

构建流程简述：

三、配置示例

Webpack 5

一、Remote 应用（暴露模块）

二、Host 应用（消费模块）

在 Host 中使用 Remote 模块

Rsbuild

✅ 前提：安装工具

一、Remote 应用（Provider）配置

目录结构（简化）

1. src/Button.tsx

2. rsbuild.config.ts（关键：暴露模块）

3. 启动 Remote

二、Host 应用（Consumer）配置

目录结构

1. src/App.tsx

2. rsbuild.config.ts（关键：声明 remotes）

3. 启动 Host

四、优势

五、常见使用场景

六、注意事项与挑战

七、与其他微前端方案对比

八、未来展望

九、实际项目改造

1、改造前的关键准备工作

✅ 1. 明确改造目标

✅ 2. 统一基础依赖版本

✅ 3. 评估项目结构

2、改造过程中必须注意的事项

🔒 1. 共享依赖（Shared Dependencies）配置要精准

🌐 2. 远程入口地址（remoteEntry.js）管理

🧱 3. 路由协调（如果涉及页面级微前端）

🎨 4. 样式隔离与冲突处理

📦 5. 资产路径（静态资源）问题

3、改造中常见的难点与解决方案

4、推荐改造步骤（渐进式）

5、工具链建议

6、总结：成功改造的关键

总结

直通车

1. `src/Button.tsx`

2. `rsbuild.config.ts`（关键：暴露模块）

1. `src/App.tsx`

2. `rsbuild.config.ts`（关键：声明 remotes）