进阶:微前端与大型应用拆分
本篇要点:能判断一个大型 Vue 应用该不该拆成微前端(micro frontend),并在 qiankun 与 Module Federation 之间做出有依据的选择,写对生命周期与卸载。前置文章:《进阶:Monorepo 与组件库发布》把仓库拆成了多个包,这一章解决"已经上线的多个应用怎么在浏览器里拼成一个"。
为什么需要它
有一个三十万行的后台,用 qiankun 跑了两年,菜单切换越来越卡。用户投诉"点几次菜单浏览器就卡",但复现不了,测试环境一切正常。
打开 DevTools 的 Performance 面板才看清:每切一次菜单,样式表里的 CSS 规则数涨三百多条。挂载从来不是难点,泄漏才是。这套系统后来有一半换成了 Module Federation(简称 MF),两套方案都在线上跑满一年。
版本先摆出来,免得对不上。qiankun 2.10.16(2023-11-15 发布,截至 2026 年 11 月仍是 npm 上的 latest)、@module-federation/enhanced 2.9.3(2026-11-03)、@module-federation/vite 1.24.1(2026-11-15)、Vue 3.5.x + Vite 8.x。qiankun 3.0 从 2023 年 9 月进 RC,到 2026 年 8 月 30 日的 3.0.0-rc.22 仍未 GA。
拆分不是万能药。表 12-1 列出四种常见诉求,只有前三条能靠微前端解决。
| 诉求 | 典型表现 | 微前端能解决吗 |
|---|---|---|
| 构建与发布耦合 | 改一个菜单要等全量构建、整体回滚 | 能,子应用独立构建独立部署 |
| 技术栈异构 | 老页面是 jQuery 或 Vue 2,无法重写 | 能,qiankun 接 HTML 入口即可 |
| 团队边界 | 多个团队在同一仓库互相阻塞 | 能,按业务域划子应用 |
| 单个页面卡顿 | 长列表滚动掉帧、首屏白屏久 | 不能,那是渲染性能问题,见《性能优化:渲染性能、长列表与加载策略》 |
核心概念
微前端与两种集成方式
微前端是把一个前端应用按业务域拆成若干可独立开发、独立部署的子应用(micro app),运行时在浏览器里组合成一个页面。
两种集成方式差别很大。HTML 入口(HTML Entry)在运行时拉取子应用的 HTML,解析出 JS 与 CSS 再执行,qiankun 走这条;模块共享在构建期声明 remote,运行时按需加载远程模块,MF 走这条。
可以类比成:HTML 入口像一个"共享同一个 window 的 iframe",模块共享像"运行时 import 一个别人部署好的包"。
反例很常见:五个人维护的后台拆成四个子应用,理由是"以后会有人接手"。结果是本地起四个 dev server、登录态同步四次、一个 bug 要开四个仓库找。他们真正需要的只是一个 npm 包,或者 workspace 里的一个本地包。
生命周期与沙箱
qiankun 要求子应用导出 bootstrap、mount、unmount 三个函数。沙箱(sandbox)是一个 Proxy 假 window,拦截子应用对 window 的读写,卸载时把改动还原。
关键在于:它还原的是 window 上的属性,不是你写的 setInterval、window.addEventListener('resize'),也不是模块作用域里的单例。有个子应用把轮询订单状态的定时器写在 setup() 外面,unmount 里没人管它。用户切了二十次菜单,二十个定时器一起跑,这就是那次"点几次就卡"的真正原因。
由此得出一条接入约定:任何子应用的 unmount 必须能被单独审视,只允许有清理逻辑,不允许有异步收尾。异步收尾意味着你永远不知道它到底跑完没有。
两个与挂载相关、报错却很难看的点。一是 publicPath:子应用部署在 CDN 子路径时必须是绝对地址,否则 HTML 入口拉到的 JS 全部 404,主应用只报一句脚本执行失败。二是跨域(CORS):入口域名要对主应用开放,且 HTML、JS、CSS 三类资源都要能 fetch——只放行 JS 不放行 CSS 是常见配置,结果是页面空白、样式全丢。
工具链也要对得上。vite-plugin-qiankun 最后一次发布是 2022-07-17 的 1.0.15,在 Vite 8 上不要指望它。手动把生命周期挂到 window[appName] 更可控,多写十几行,出问题时知道在哪。
共享依赖与单例
换成 MF 的动机很实际:三个子应用各带一份 Vue,首屏光框架就一百多 KB。
MF 的做法是把 vue、vue-router、pinia 声明成 singleton,谁先加载用谁的。收益是真的,官方博客给过一组数:一个只用到 Badge/Button/List 的应用接入 Ant Design,共享依赖未开 tree shaking 时共享包约 1404.2 KB,开了之后约 344.0 KB。
代价是排查变难。Vue 装了两份时,组件照样渲染,inject 全是 undefined,Teleport 的目标跑到另一个 document 片段里去。你去搜报错,搜到的是"inject 返回空",报错本身不会提微前端一个字。
仓库一旦上了 pnpm workspace,还有一层:软链会让同一份依赖在 host 和 remote 里解析出不同的绝对路径,MF 就把它们当成两个模块,singleton 白配。要加 allowNodeModulesSuffixMatch: true,按 node_modules/ 之后的部分比对。常见现象是"本地正常,预发环境 inject 全空"。
requiredVersion 也有代价:remote 升级 Vue 会触发告警,而告警在控制台里是黄色的,没人看。后来把它接到了 CI 上,构建时检查产物里 Vue 只出现一次,比人盯控制台靠谱。
样式隔离的真实边界
MF 官方 FAQ 写得很直白:Module Federation 本身不提供样式隔离,理由是 shared 复用依赖会让模块逃逸出任何沙箱边界,运行时擦 CSS 的边界情况根本没法排查。它给的方向是在生产者侧解决——CSS Modules、BEM 前缀、统一组件库版本。MF 2.0 的 Side Effect Scanner 能静态扫出全局变量、事件监听、CSS 选择器的影响范围,那是治理,不是隔离。
qiankun 有两档。experimentalStyleIsolation 用选择器前缀改写,但它不改 @keyframes、@font-face、@import、@page,动画名和字体族仍然是全局的,得自己加前缀。strictStyleIsolation 包一层 Shadow DOM,而 Element Plus 这类库的弹窗、下拉、日期选择器大量 Teleport 到 body,一挂上去样式直接失效,组件库源码你又改不了。
一个不优雅但有效的做法:组件库统一到同一版本,宿主在 body 上加一个数据属性作为命名空间,所有覆盖样式挂在这个属性底下。
通信与灰度
initGlobalState 只能修改已存在的一级属性。子应用里 setGlobalState({ newField: 1 }) 是彻底无效的,新字段必须在初始 state 里先占位。
灰度切换的坑在"已挂载"三个字。registerRemotes({ force: true }) 能覆盖已注册的模块、清掉模块缓存,但已经挂在页面上的组件不会自己重新渲染。用户看到的还是旧组件,只有下一次路由进入才换新的。灰度验证时在测试环境点了半天觉得生效了,其实是因为每次都刷新了页面。
动手实践
步骤 1:让子应用的卸载可被审查
// 子应用 src/main.ts —— 修好之后
import { createApp, type App as VueApp } from 'vue'
import App from './App.vue'
import { createRouter, createWebHistory } from 'vue-router'
import { routes } from './router'
import { pollOrder } from './services/order'
let app: VueApp | null = null
let timer: number | null = null
;(window as Record<string, unknown>)['order-web'] = {
mount: async (props: { container?: HTMLElement }) => {
app = createApp(App)
app.use(createRouter({ history: createWebHistory('/order'), routes }))
app.mount(props.container?.querySelector('#app') ?? '#app')
timer = window.setInterval(pollOrder, 5000)
},
unmount: async () => {
if (timer) { window.clearInterval(timer); timer = null }
app?.unmount()
app = null
},
}预期输出:调用 window['order-web'].unmount() 之后定时器被清掉、timer 回到 null;连续切换菜单二十次,Performance 面板里的定时器数量与 CSS 规则数保持平稳,不再逐次上涨。
清理写在 app.unmount() 之前:卸载过程会触发 onUnmounted 钩子,钩子里不该再有一个还在跑的轮询。
步骤 2:在宿主声明 remote 与共享单例
// host vite.config.ts —— @module-federation/vite 1.24.x
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import { federation } from '@module-federation/vite'
export default defineConfig({
plugins: [
vue(),
federation({
name: 'shell',
manifest: true,
// pnpm workspace 下必须加,否则软链路径不同会被当成两个模块
allowNodeModulesSuffixMatch: true,
remotes: {
orderWeb: { type: 'module', name: 'orderWeb', entry: 'https://order.example.com/mf-manifest.json' },
},
shared: {
vue: { singleton: true, requiredVersion: '^3.5.0' },
'vue-router': { singleton: true, requiredVersion: '^4.4.0' },
pinia: { singleton: true },
},
}),
],
})预期输出:宿主里 loadRemote('orderWeb/App') 能取到组件并渲染;产物里搜索 vue 的运行时特征只出现一次,inject 能拿到宿主 provide 的值。去掉 allowNodeModulesSuffixMatch 后,预发环境 inject 变 undefined,本地仍正常。
步骤 3:让每个挂载器都返回卸载函数
// host src/micro/registry.ts
import { registerRemotes } from '@module-federation/enhanced/runtime'
export type Mounter = (el: HTMLElement) => Promise<() => void>
const unmounters = new Map<string, () => void>()
export async function mountRoute(key: string, mounter: Mounter, el: HTMLElement) {
unmountRoute(key) // 同一路由重复进入先卸
const unmount = await mounter(el)
unmounters.set(key, unmount)
}
export function unmountRoute(key: string) {
const fn = unmounters.get(key)
if (fn) { fn(); unmounters.delete(key) }
}
// 灰度切换:先卸载,再换入口
export async function switchRemote(entry: string) {
registerRemotes([{ name: 'orderWeb', entry }], { force: true })
unmountRoute('order')
}运行结果:switchRemote 执行后,下一次 loadRemote 拿到的是新 entry 的模块;但页面上已挂载的组件要等 unmountRoute('order') 执行并重新 mount 之后才换。路由离开时 unmountRoute 被调用,定时器与监听一起清掉。
这条规则顺带解决了共存问题。老系统继续走 qiankun 的 HTML 入口,新模块走 loadRemote,路由层一个路由对一个挂载器,迁移按菜单粒度推进,如图 12-1 所示。
图 12-1 主应用按路由分派挂载器,两种加载方式在同一层收口
回到图 12-1,值得停一下的是最后一步。卸载不是"路由走了就算了",它必须显式调用挂载器返回的函数。线上那次卡顿,就是这条回边断掉了。
步骤 4:先回答一个问题,再选型
表 12-2 qiankun 与 Module Federation 的对照
| 维度 | qiankun 2.x | Module Federation 2.x |
|---|---|---|
| 隔离 | Proxy 假 window,样式靠前缀或 Shadow DOM | 无沙箱,共享同一个 window |
| 依赖共享 | 不共享,Vue 多实例常见 | shared 协商,单例复用 |
| 技术栈异构 | 强,jQuery、Vue 2 都能接 | 弱,要求同一套构建体系 |
| 路由归属 | 主应用 activeRule,子应用 history base | 子应用当组件挂,路由由宿主主导 |
| 主要故障形态 | 副作用泄漏、样式互串 | 版本协商失败、单例被打破 |
拿不准的时候只问一个问题:能不能统一 Vue 版本。能统一,MF 的治理成本低于 qiankun 的沙箱调试成本;不能统一,MF 的 shared 会变成一场持续的版本谈判,qiankun 反而省心。
常见误解
很多人以为沙箱能兜住子应用的所有副作用。 沙箱只还原它拦截到的那部分 window 写入。定时器、事件监听、模块级单例都不在其中,而泄漏的子应用往往不是最重要的那个,是三年前别人交接过来的那个。
很多人以为 MF 自带样式隔离。 官方 FAQ 明确说不提供,因为共享依赖让模块本来就在沙箱边界之外。能做的只有生产者侧约束:CSS Modules、BEM 前缀、统一组件库版本。
很多人以为 registerRemotes({ force: true }) 会立刻替换页面上的组件。 它替换的是模块注册表和模块缓存,已挂载的组件不会重新渲染,只有下一次路由进入才换。想立即生效,必须配一个显式的卸载函数。
很多人以为微前端是"以后会有人接手"的解法。 它是组织问题的解法,不是代码问题的解法。一个团队、一套技术栈、一个发布节奏时,拆开只会把一次改动变成四次联调。
小结
- 微前端解决发布耦合、技术栈异构与团队边界三类问题,解决不了渲染性能问题;单团队单技术栈时不该拆。
- qiankun 的价值在隔离与兼容:Proxy 假 window 加 HTML 入口,能让 jQuery 老系统不改一行接进来。它的沙箱不管定时器与监听,
unmount必须只做清理、不做异步收尾。 - MF 的价值在依赖共享与包体积:
shared单例让三个 Vue 合成一个,代价是双实例时inject、Teleport的报错完全不指向根因;pnpm 仓库要加allowNodeModulesSuffixMatch。 - 样式隔离要靠约定而不是工具:qiankun 的前缀改写绕过
@keyframes与@font-face,strictStyleIsolation会撞上Teleport到 body 的弹窗。 - 无论挂的是哪一套,宿主都只认"返回卸载函数的挂载器",一个路由一个挂载器,卸载显式调用。《进阶:Monorepo 与组件库发布》解决仓库内的多包协同,这一章解决运行时的多应用协同。
相关主题
这是本类目的收尾篇。回头看这条线:《Vue 3 基础:响应式原理、组件与组合式 API》的响应式与组合式 API 是地基,类型安全、构建工具、路由与状态管理补齐工程骨架,请求层、可复用组件、性能优化与测试决定它跑得好不好,服务端渲染把它带到能被搜索引擎读到的地方,而这一篇把视角从"一个应用"抬到"一组包、一组应用"。接下来最值得做的一件事,是拿自己手上的项目对照这三层问题做一次盘点——哪些是单应用内部的事,哪些该拆成包,哪些根本不该拆。答案通常比想象中保守。要回看地基,《Vue 3 基础:响应式原理、组件与组合式 API》是最值得重读的一篇。