微前端共享依赖：省包体之前，先确认版本契约

一、共享依赖不是免费优化

微前端项目里，多个子应用都会用 React、Vue、组件库、图表库。为了减少重复下载，团队很容易想到共享依赖。思路没错，但共享依赖不是免费优化。它把包体问题变成了版本契约问题。

如果主应用提供 React 18，某个子应用却按 React 19 的行为开发；如果设计系统组件库版本不同，按钮样式和表单校验就可能在不同页面表现不一致。包少了，但风险转移到了运行时。

二、先画清依赖关系

flowchart TD Shell[主应用 Shell] --> Shared[共享依赖层] AppA[订单子应用] --> Shared AppB[报表子应用] --> Shared AppC[设置子应用] --> Shared Shared --> React[React] Shared --> UI[Design System] Shared --> Router[Router]

不是所有依赖都适合共享。框架运行时、设计系统、日期库这类基础依赖可以考虑共享；业务 SDK、页面私有工具、实验性库则更适合跟随子应用发布。共享范围越大，协调成本越高。

判断一个依赖能否共享，可以看三个问题：版本是否长期稳定，破坏性升级频率高不高，多个子应用是否必须保持一致。如果答案不明确，先不要为了节省几十 KB 把它放进全局。

三、版本契约要写进发布流程

{ "shared": { "react": { "requiredVersion": "^18.3.0", "singleton": true }, "@acme/design-system": { "requiredVersion": "5.x", "singleton": true } } }

共享依赖需要明确版本范围、是否单例、由谁提供、谁负责升级。只在 webpack 或模块联邦配置里写一行不够，还要把契约写进文档和 CI。

shared_dependency_gate: react: allowed: "^18.3.0" design_system: allowed: "5.x" block_on_mismatch: true

CI 可以扫描每个子应用的package.json，发现共享依赖越界时直接阻塞。这样问题在合并前暴露，而不是等用户打开某个组合页面时才崩。CI 扫描要同时检查 lock 文件，因为package.json里的范围声明和实际安装版本可能不一致。

四、运行时要能定位责任

共享依赖出问题时，排查经常很痛苦：到底是主应用升级了，还是子应用打包配置错了，还是 CDN 缓存了旧资源。运行时应打印子应用版本、共享依赖版本和加载来源。

window.__MICRO_APP_MANIFEST__ = { app: "report", version: "2026.07.04", shared: { react: "18.3.1", designSystem: "5.8.0" } }

还要准备降级策略。某个子应用如果暂时无法跟上共享依赖版本，可以允许它短期内自带依赖，但必须标记为例外，并设置到期时间。例外长期存在，微前端共享层就会慢慢失去治理价值。

共享依赖升级也要有演练环境。主应用先加载新版本共享层，再挂载所有核心子应用，跑一组跨应用流程：登录后进入报表、从订单跳转到设置、主题切换后返回列表。很多问题不会出现在单个子应用里，只会出现在组合运行时。

micro_frontend_upgrade_check: shared_layer: "2026.07.04" apps: - order - report - settings checks: - route_switch - theme_consistency - shared_store_compatibility

如果团队没有能力持续维护共享层，宁愿先接受一部分重复包体。微前端的目标是让组织和发布更灵活，不是把所有依赖都变成全局单点。

实际排查时，光在控制台打印版本信息还不够，需要建立一套运行时兼容检查。子应用挂载前先和主应用对版本号，不兼容时走降级路径，而不是直接崩溃：

function checkSharedCompat(manifest: MicroAppManifest, required: SharedContract) { const issues: string[] = [] for (const [lib, range] of Object.entries(required)) { const actual = manifest.shared[lib] if (!actual) { issues.push(`子应用缺少共享依赖: ${lib}`) continue } if (!semver.satisfies(actual, range)) { issues.push(`${lib}: 需要 ${range}，当前 ${actual} — 不兼容`) } } return { compatible: issues.length === 0, issues, strategy: issues.length > 0 ? "隔离运行" : "共享实例", } }

这个方法在生产环境的一个具体收益是：某个子应用使用了较新版本的设计系统组件，但主应用共享的是旧版本，如果直接挂载会报出TypeError: component is not a function。加了兼容检查后，不兼容的子应用会降级为自带依赖模式运行，虽然包体多了一点，但页面不崩。后面团队有了排期窗口再统一升级共享层，用户体验全程不受影响。

五、总结

微前端共享依赖的价值不只是省包体，更重要的是让多个子应用在基础能力上保持一致。

共享之前要确认版本契约、发布责任、CI 门禁和运行时诊断。否则省下来的下载量，很快会变成更难排查的线上问题。