Skip to content

进阶:微前端与大型应用拆分 ​

本篇要点:能判断一个大型 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:让子应用的卸载可被审查 ​

ts
// 子应用 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 与共享单例 ​

ts
// 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:让每个挂载器都返回卸载函数 ​

ts
// 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.xModule 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》是最值得重读的一篇。