这阵子在啃 kpay-crm-web 的微前端架构。读文档总是在「大概懂了」和「真说不清」之间摇摆,于是干脆按源码把整条链路捋了一遍,写成一份手册,又配了个能在浏览器里点着玩的实验室,一起存进博客。
两份东西都能直接点开:
手册是单文件 HTML,实验室是一整个目录(纯原生 JS,无构建、无依赖、无网络请求),都不需要本地起服务。
全景:一个 URL 走完全程
手册开篇用一张图把整条路串起来,起点是地址栏,终点是子应用的 React 代码跑在基座页面里:
http://crm-sg-test.kpay-test.com/system/roleList
│
▼
基座 kpay-crm-web(umi SPA)
umi 匹配到 /system/roleList
→ component = <MicroAppMain name="iam-app" url="http://iam.test.a.../">
│
▼
浏览器自定义元素 <micro-app name url>
│
▼
micro-app 运行时
├─ fetch(url) 拿到子应用 index.html
├─ 拆成 <micro-app-head> + <micro-app-body>
├─ 建 with 沙箱(伪 window + Proxy)
├─ 把子应用的 <script> 包进 with(...) 执行
└─ CSS 选择器加前缀 micro-app[name=iam-app]
│
▼
子应用 React 代码跑在基座页面里
DOM 挂在 <micro-app-body> 下
侧边栏因 __MICRO_APP_ENVIRONMENT__ 而不渲染
先说清几个名词,后面才不会打架:
最后一行是最容易搞错的一条,下面会专门说。
四块原生基础
微前端听起来复杂,剥到底层其实是四个浏览器原生能力拼起来的,手册第 1–4 章一章讲一块:
关于 §2 有一点值得记:micro-app 并没有真的用 Shadow DOM 做隔离,而是在构建时给 CSS 选择器加宿主前缀(micro-app[name=iam-app] .btn)。手册里管它叫「改造版」——因为它保留了 Shadow DOM 的隔离效果,却避开了 Shadow DOM 带来的 React 事件代理、第三方组件库样式穿透这些麻烦。
§4 那条也解释了为什么不用 iframe:iframe 能装任意站点,代价是子应用的弹窗出不了框、基座拿不到子应用的 DOM、路由和滚动都要跨窗口通信。而微前端要的是看起来像同一个页面,所以必须把 DOM 搬进来。
沙箱是整份手册里最绕的一块
第三章用了 400 多行,因为它有三层对象叠在一起,第一次看几乎必然晕。核心其实只有一句话:读穿透,写隔离。
真 window (rawWindow)
▲ 读穿透(沙箱里找不到就回落到这里)
│
proxyWindow = new Proxy(microAppWindow) ← 子应用代码里的 window 就是它
▲
│ __MICRO_APP_WINDOW__ 指向
microAppWindow = new CustomWindow() ← with 的作用域对象,子应用全局变量都在这
microAppWindow是「搬家后的 window」,变量真的存在这proxyWindow是门面,负责读穿透和几处特殊映射(location、Worker)with (proxyWindow.__MICRO_APP_WINDOW__) { ... }让子应用脚本里的自由变量查找先落到沙箱上
光有 with 不够,还得让子应用的 <script> 在 with 里执行,所以要重写代码:
;(function (proxyWindow) {
with (proxyWindow.__MICRO_APP_WINDOW__) {
(function (window, self, globalThis, document, ...) {
/* 子应用原始代码原封不动放这里 */
}).call(proxyWindow, window, self, globalThis, document, ...);
}
})(window.__MICRO_APP_PROXY_WINDOW__);
另外还有几类 API 必须额外打补丁,否则沙箱就是漏的:
window.microApp 不是沙箱
这条单独拎出来,因为它是最容易混淆的一点。源码里给子应用注入的是这一行:
microAppWindow.microApp = assign(new EventCenterForMicroApp(appName), {
removeDomScope, pureCreateElement, location: microAppWindow.location, router,
});
也就是说,microApp 只是被塞进沙箱的一个属性,它自己是个通信对象。沙箱负责「隔离」,window.microApp 负责「通信」,两者是并列关系,不是容器关系。
判断「我在不在沙箱里」的标志也不是 microApp 存不存在,而是:
window.__MICRO_APP_ENVIRONMENT__ === true
手册里列了沙箱注入的一整组全局变量(__MICRO_APP_NAME__、__MICRO_APP_URL__、__MICRO_APP_PUBLIC_PATH__、__MICRO_APP_BASE_ROUTE__、__MICRO_APP_SANDBOX_TYPE__、rawWindow……),并给了一条排查命令:
window.__MICRO_APP_PROXY_WINDOW__ // with 沙箱下才有
document.querySelector('micro-app').__MICRO_APP_NAME__
通信:为什么不是 postMessage
这是我在读之前想当然搞错的地方。
postMessage 是跨域场景的手段——iframe 之间、不同 origin 的窗口之间,因为拿不到对方的 JS 运行时,只能序列化字符串过去。但本项目的子应用和基座同源部署、共享同一个 JS 运行时,直接传对象引用就行,没有任何序列化成本。
micro-app 也没用 DOM 的 CustomEvent,而是自己写了一个轻量的 EventCenter(Map 存 name -> { data, callbacks })。事件名用 appName 拼成 __iam-app_from_base_app__ 这种形式,保证不同子应用互不干扰。
四组 API 对应四个方向:
forceDispatch 是「请求-响应」模式,本项目拿它做 token 刷新:子应用发一句「帮我刷一下」,基座 listener 里 await _refreshToken(),把结果 return 回去,子应用在回调里拿到新的 accessToken。
还有一个设计细节值得记:setData 是带缓存的。基座在 onBeforemount 里就先 setData 下发权限和语言,此时子应用可能连监听都还没绑上;等子应用启动绑定时,addDataListener(appName, cb, autoTrigger) 的第三个参数会让它立刻收到那份缓存。先发后订阅不会丢消息。
路由:native-scope
子应用自带 react-router,它要读 window.location.pathname。但在基座里,location 是基座的 /system/roleList,子应用想看到的是「自己的」路径,push 时又不能把基座地址栏改乱。
micro-app 给了五种模式,本项目用的是 native-scope:地址栏用基座的,但子应用视角的 location.origin / location.href 指回子应用自己的域名。
这一条不是洁癖,是实用:子应用里 window.location.href 拿到的是 http://iam.test.a.../system/roleList,所以它拼资源路径、跳登录页时不会跑到基座域名下。
至于同步方向,手册里总结了八个字——基座永远不改子应用的内部路由,只告诉它「地址变了」:
export function onRouteChange({ location, matchedRoutes }) {
const last = matchedRoutes[matchedRoutes.length - 1]?.route;
if (last?.system) { // 只有子应用路由才有 system 字段
microApp.setData(last.system, {
location,
masterOrigin: window.location.origin,
type: MICRO_APP_TYPE.MASTER_ROUTES_CHANGE,
});
}
}
接地气的部分:14 个子应用怎么管
前面六章讲原理,第七章讲 @kpay/adapter 这层封装——结论有点出乎意料:@kpay/adapter-micro-app 的 index.js 全文只有 8 行,只是把第三方的 microApp 换个名字再导出,再加两个自己写的组件,没有包任何逻辑。价值不在「封装」,在于依赖树收敛:业务侧只依赖 @kpay/adapter 一个包,底下 micro-app 升版时不用挨个仓库改。
第八章是真正会天天用到的落地约定:
新增一个子应用页面,五步。
- 建
src/MicroApp/SubApp/XxxApp.tsx - 声明路由,每条带
system: appName和component - 指定
anchor: { name: 'system', position: 'child' | 'before' | 'after' }—— 决定菜单挂在哪个节点下面 - 在
src/app.tsx的patchRoutes里注册 - 在
src/MicroApp/SubApp/index.ts导出
兜底逻辑在 SubApp/utils.ts 的 commitFilterRouter 末尾:没被任何 anchor 认领的节点,会被 push 到菜单末尾,不会凭空消失。
地址注入是三段接力:构建期 document.ejs 里写占位符 UMI_APP_SUB_IAM_APP_URL → 运行期容器脚本 env_read.sh 替换 → 浏览器里从 window.env.SUB_IAM_APP_URL_VALUE 读出来。自查用一条命令:
curl -s http://<环境域名>/ | grep -c "UMI_APP_"
输出大于 0,说明有占位符没被替换。
子应用侧三条约定:检测到 __MICRO_APP_ENVIRONMENT__ 就不渲染自己的 Layout;路由跳转走 dispatch(CONTROLLER_ROUTE_CHANGE),不要 history.push;不要改 document.title 和 document.body 的样式。
排错清单
第九章是一张症状对照表,八条,都是实际踩过的:
调试常用这几句:microApp.getAllApps()、microApp.getActiveApps()、microApp.getData('iam-app')、document.querySelector('micro-app[name=iam-app]').querySelector('micro-app-body')。
第十章留了 10 道自检题,每题标了答案在哪一节。我现在能答上七八道——剩下两三道(沙箱对 instanceof 的影响、native-scope 下后退键的行为)还得回头翻源码。
七个实验
手册是读的,实验室是动手的。七个 Lab 和 §1–§7 一一对应:
每个 Lab 底部有一组验收断言,全部通过才算完成;进度存在 localStorage 里,顶部进度条会走。
一点体会
写这份东西最大的收获,不是搞懂了某个 API,而是发现很多「架构」拆开之后,剩下的都是几个浏览器原生能力。Custom Elements、Shadow DOM、Proxy、DOMParser——每一样单独看都是前端基础课里的东西,单独用也都不稀奇。微前端的复杂度在于把它们串起来时,每一处都要考虑「如果这里不补一刀会怎样」。
沙箱那一章最典型。with + Proxy 五十行就能写出一个能跑的版本,但真到生产环境,光有五十行是不够的——addEventListener 不清会泄漏,setInterval 不清会泄漏,document.querySelector 不限范围会查到别人的 DOM,history.pushState 不管会改掉基座的地址栏。手册第三章的后半部分(§3.10 源码级实现)整整 340 行,全在讲这些「一刀」。原理是干净的,落地是脏的。
另一个体会是关于写文档这件事本身。我一开始想按知识点组织——沙箱、通信、路由各写一章。写到一半发现不行,因为读者(其实是我自己)真正会问的问题是「菜单点一下,到底发生了什么」。所以最后加了第 0 章那张全景图和 §5.4 的挂载时序,把纵向的时间轴摆在横向的知识点前面。先给一条能走通的路,再解释路上的每一块砖,比堆术语好用得多。
最后是那个实验室。手册写到第七遍「读穿透、写隔离」的时候,我意识到这句话我已经能背了,但还是说不清某个具体场景下到底走的是哪条分支。于是把 Proxy 的 get / set / has 做成了能单步触发的东西——自己动手点两次,比读十遍强。这也算是把 10 月 15 日那篇里 Karpathy 的说法真正用了一次:文字适合查阅,交互网页适合自己动手探索,两者不是替代关系。