微前端实战：3001端口暴露的组件陷阱

一个React应用只占3001端口，却能被主应用远程调用——这听起来像魔法，其实是Webpack模块联邦（Module Federation）的标准操作。但配置文件的23行代码里，藏着3个让新手崩溃的坑。

为什么"暴露"比"导出"复杂得多

普通React组件用export default就能复用，微前端却要绕一大圈。因为主应用（Shell）和远程应用（Remote）是两个独立构建、独立部署、甚至独立团队维护的项目。

原文的配置逻辑很直白：远程应用需要生成一个remoteEntry.js清单文件，告诉主应用"我有什么、在哪拿"。但魔鬼在细节——publicPath必须写成完整URL（http://localhost:3001/），不能用相对路径。否则主应用加载时会拼接错误地址，白屏报错。

更隐蔽的是singleton: true。React官方文档从没提过这个配置，但模块联邦强制要求。原理很简单：如果主应用和远程应用各跑一个React实例，Hooks会彻底错乱。强制单例就是给两个独立构建体共享同一个React运行时——代价是版本必须严格一致。

bootstrap.js：一个文件解决"谁先启动"的竞态问题

原文第四步提到拆分bootstrap.js，这步最容易被跳过。直接看问题：如果index.js里直接写ReactDOM.render，模块联邦的异步加载逻辑还没执行完，应用就尝试挂载DOM——结果是不可预测的白屏或报错。

正确姿势是把渲染逻辑拆出去：

// index.js
import('./bootstrap');

// bootstrap.js
import React from 'react';
import ReactDOM from 'react-dom';
import App from './App';

ReactDOM.render(, document.getElementById('root'));

动态import()会返回一个Promise，模块联邦利用这个时机完成远程模块的注册和共享依赖的解析。等Promise resolve，应用才正式渲染。这行代码的延迟通常<100ms，但彻底消灭了竞态条件。

shared配置：版本锁定的隐形契约

原文的shared字段只写了三个库，但实际生产环境要复杂得多。模块联邦的共享机制有个前提：主应用和远程应用的依赖版本必须兼容。如果主应用用React 18.2.0，远程应用用18.3.0，singleton: true会强制选一个——但选哪个？

Webpack的策略是"高版本优先"，但这不是免死金牌。如果版本差异大到API不兼容（比如React 17和18），运行时直接崩溃。所以微前端架构对团队的依赖管理提出了硬性要求：要么统一锁定版本，要么在CI里加版本校验。

原文没提但实战中必踩的坑：@shared别名指向的共享库。如果多个远程应用都引用同一个本地路径的共享库，构建时会各自打包一份，违背"共享"初衷。正确做法是把共享库发布到私有npm，或配置模块联邦的shared时显式声明版本范围。

端口冲突与开发体验

原文把远程应用跑在3001端口，主应用默认3000。这设计有讲究：模块联邦要求远程应用的publicPath和实际运行地址完全一致，否则远程入口文件加载后，内部的异步分块（chunk）会请求错误地址。

开发环境下，这意味着每个远程应用需要固定端口。团队规模扩大后，端口分配变成行政问题——谁占3002？3003？有没有文档记录？

更头疼的是热更新（HMR）。模块联邦的远程应用支持HMR，但配置繁琐，且主应用不会自动感知远程应用的代码变化。原文没展开，但生产级方案通常需要@module-federation/enhanced插件或自定义轮询逻辑。

暴露的粒度：组件级还是路由级？

原文示例暴露了一个./Test组件，但真实项目很少这么细粒度。常见做法是暴露整个路由配置：

exposes: {
'./Routes': './src/entry.routes.jsx'
}

这样主应用可以用React.lazy动态加载远程路由，像加载本地组件一样自然。但代价是远程应用的路由结构必须扁平化，不能嵌套太多层——否则主应用的路由解析会混乱。

另一种极端是暴露整个应用壳（App Shell），让远程应用几乎独立运行。这适合遗留系统迁移，但违背了微前端"组合而非替换"的初衷。

构建产物的秘密：remoteEntry.js里有什么

运行npm run build后，dist/remoteEntry.js只有几十KB，却是整个远程应用的入口。它本质上是一个模块注册表，包含：

• 远程应用名称（mfe1）
• 暴露模块的映射表（./Test → 实际chunk文件名）
• 共享依赖的版本协商逻辑
• 运行时加载器（从publicPath拉取实际代码）

主应用加载时，先请求这个入口文件，解析出需要哪些chunk，再并行加载。如果publicPath配的是CDN地址，这些chunk可以走全球加速；如果配的是相对路径，主应用和远程应用必须同源部署。

原文的historyApiFallback: true也是为开发环境服务——防止刷新404。生产环境通常由Nginx或CDN处理路由回退，不需要Webpack DevServer操心。

为什么这套方案能活到现在

模块联邦2019年发布时，微前端还是"炫技"概念。五年过去，它成了大型前端团队的标配。不是因为完美，而是因为替代方案更糟：

• iframe方案：隔离性强，但弹窗遮罩、路由同步、性能开销全是坑
• Web Components：标准方案，但框架互操作性差，React团队自己都不用
• Monorepo统一构建：解决共享依赖，但发布耦合，违背微前端独立部署的初衷

模块联邦的妥协在于：接受构建时的复杂度，换取运行时的灵活性。每个远程应用独立构建、独立部署、独立回滚，主应用只在运行时组装。这对"一个团队维护一个业务域"的组织架构极其友好。

原文的配置是"最小可用"版本，离生产环境还差：错误边界（远程应用加载失败怎么办）、性能监控（chunk加载时长）、版本协商（共享依赖冲突时的降级策略）、安全沙箱（远程代码的权限控制）。但这些不是模块联邦的缺陷，是任何分布式系统都要面对的工程问题。

3001端口跑起来的不只是一个React应用，是一套组织协作的契约。代码是表象，背后是团队边界、发布节奏和技术债的重新谈判。