illegalCreed

中文

English

中文

English

Appearance

参考 ​

基于 qiankun 2.10（3.0 rc 追踪） · 核于 2026-07

速查 ​

  • 本页汇总六张表：核心 API / 三沙箱对比 / 样式隔离两方案 / UMD 接入清单 / Vite 方案 / 版本时间线
  • 核心 API 一句话：路由型 registerMicroApps + start（默认 singular: true 单实例）、手动型 loadMicroApp（多实例、生命周期自管）、initGlobalState 通信、setDefaultMountApp/runAfterFirstMounted 管启动
  • 三沙箱一句话：proxySandbox（多实例）/ legacyProxySandbox（单实例）/ snapshotSandbox（无 Proxy 降级），按「有无 Proxy + singular」自动选
  • 样式隔离一句话：strictStyleIsolation（Shadow DOM，弹窗逃逸）vs experimentalStyleIsolation（属性改写，不支持 @keyframes/@font-face）；主应用样式自治靠改前缀
  • UMD 接入一句话：libraryTarget: 'umd' + 唯一 library/chunkLoadingGlobal + 导出 bootstrap/mount/unmount + 修 __INJECTED_PUBLIC_PATH_BY_QIANKUN__ + 开 CORS
  • Vite 一句话：2.x 基于 import-html-entry 不支持 ESM 入口，vite-plugin-qiankun 可 hack（沙箱失效），要真隔离换 wujie/micro-app，3.0 规划原生吃 ESM
  • 版本一句话：2.10.16（2023-11）事实稳定线，3.0 rc.21（2026-02）仍无 stable，三年难产、2026 复苏（@scope、create-qiankun）
  • 定位一句话：qiankun = single-spa + HTML entry + JS 沙箱 + 样式隔离；国内存量最大、面试必考，甜区「存量 webpack + 要开箱」

一、核心 API 表 ​

API作用关键参数 / 返回
registerMicroApps(apps, lifeCycles?)路由型注册子应用app：name/entry/container/activeRule（+loader/props）；全局 beforeLoad/beforeMount/afterMount/beforeUnmount/afterUnmount
start(opts?)启动 qiankunprefetch（默认 true）/sandbox（默认 true）/singular（默认 true）/fetch/getPublicPath/getTemplate/excludeAssetFilter
loadMicroApp(app, config?)手动加载（多实例）返回 MicroApp：mount/unmount/update/getStatus/loadPromise/bootstrapPromise/mountPromise/unmountPromise
setDefaultMountApp(appLink)首次进站默认挂载的子应用路由字符串（如 /home）
runAfterFirstMounted(effect)首个子应用挂载后执行一次回调（常用于收 loading）
initGlobalState(state)建全局通信状态返回 onGlobalStateChange(cb, fireImmediately?)/setGlobalState(state)（仅一级属性）/offGlobalStateChange()
prefetchApps(apps, opts?)手动预取子应用资源[{ name, entry }]
addGlobalUncaughtErrorHandler(h) / removeGlobalUncaughtErrorHandler(h)全局未捕获错误兜底错误处理器

entry 可为 HTML 地址（末尾 / 不能省）或 { scripts, styles, html }；activeRule 可为前缀串 / location => boolean / 数组。详见核心 API。

二、三沙箱对比表 ​

沙箱隔离方式实例数何时启用
proxySandbox每应用一个 fakeWindow，写落假读先假后真多实例支持 Proxy 且 singular: false
legacyProxySandboxProxy 记差异、写仍落真 window、卸载恢复单实例支持 Proxy 且 singular: true（路由型默认）
snapshotSandbox激活拍 window 快照、失活 diff 恢复单实例不支持 Proxy 的旧环境（IE）降级，强制单实例

拦得住：全局变量读写、window 事件（劫持 addEventListener 记账卸载清）、定时器（劫持 setTimeout/setInterval）、动态 <style>/<script>/<link>（记账卸载移除）。拦不住：window.top/window.parent、原生构造函数、闭包缓存引用——软隔离防意外不防恶意。高频坑：window.onXxx 直接赋值失效，改 addEventListener。沙箱通论见核心机制·JS 沙箱，qiankun 细节见沙箱实现。

三、样式隔离两方案对比表 ​

维度strictStyleIsolationexperimentalStyleIsolation
机制Shadow DOM 包裹子应用容器运行时把规则改写成 div[data-qiankun-xxx] .selector
隔离方向双向（进不来出不去）单向（防泄漏，不防入侵）
弹窗（挂 body）死穴：逃出 shadow tree、样式全丢失效：改写后选择器选不中
@keyframes/@font-face/@import/@page树内自洽（重名仍需前缀）不支持改写 → 重名互踩
继承属性 / CSS 变量照常穿透（可作主题通道）不拦
稳定度稳定但组件库弹窗致其难用实验性

默认行为（sandbox: true）：动态样式表劫持，自动隔离微应用之间的样式（卸载移除）；主应用样式不管辖。主应用自治：antd 用 modifyVars: { '@ant-prefix': 'yourPrefix' } + <ConfigProvider prefixCls="yourPrefix">。2026 方向：3.0 弃 Shadow DOM，转原生 CSS @scope。通论见核心机制·CSS 隔离，qiankun 细节见样式隔离。

四、UMD 接入清单 ​

步骤配置 / 代码目的
导出生命周期export async function bootstrap/mount/unmountqiankun 取生命周期的契约
打成 UMDoutput.libraryTarget: 'umd'否则报 “export the functional lifecycles”
库名唯一output.library: '${packageName}-[name]'多子应用不撞、qiankun 定位导出
chunk 全局唯一output.chunkLoadingGlobal（webpack4 jsonpFunction）：webpackJsonp_${packageName}避免多子应用 chunk 加载互相覆盖
UMD 挂 windowoutput.globalObject: 'window'避免 self 在某些环境出错
修 publicPath__webpack_public_path__ = window.__INJECTED_PUBLIC_PATH_BY_QIANKUN__（public-path.js 最先 import）嵌入后动态 chunk 路径不 404
判别独立/嵌入window.POWERED_BY_QIANKUN切路由 base、publicPath、是否自渲染
开 CORS资源服务器 Access-Control-Allow-Originqiankun 用 fetch 拉资源
entry 末尾带 /entry: '//host/'否则 publicPath 推断错
activeRule 错开真实路径activeRule ≠ 子应用真实访问路径否则自激活死循环

常见报错：export lifecycles（UMD/导出没对）、died in LOADING_SOURCE_CODE（entry 404/CORS/格式错）、多子应用随机失败（chunk 全局冲突）。详见 HTML entry 与接入约束。

五、Vite 方案表 ​

路线原理局限 / 适用
qiankun 2.x 原生import-html-entry「fetch 脚本回来 eval」不支持 ESM 入口 → 接不了 Vite
vite-plugin-qiankun（社区）伪装成 qiankun 认得的形式：注入全局标记、生命周期挂 window、开发态绕沙箱沙箱基本失效、非官方、生产额外配置——权宜之计
换 wujieiframe 沙箱，ESM 交浏览器原生执行原生 Vite 友好 + 隔离更强——Vite + 要隔离首选
换 micro-app支持 <script type="module">低侵入、原生 Vite 友好
single-spa + import maps原生 ESM 路线要极致控制、自建底座、自理隔离
qiankun 3.0（未 stable）新 loader：DOMParser + streaming 原生吃 ESM/Vite三年 rc、别赌排期

根因：ESM 的专属语法 / 异步原生加载 / 强制严格模式（与 with 沙箱互斥）与 import-html-entry 的 eval 模型不兼容。详见 Vite 与 ESM 之痛。

六、版本时间线表 ​

时间版本 / 节点状态
2023-11-152.10.16latest 稳定版，事实停更线（此后仅极小维护）
2021-043.0 roadmap 发起（#1378）规划
2022-06社区吐槽「一年多只做了个新 logo」停滞
2024-09-183.0.0-rc.0首个 rc（@qiankunjs/* 新架构）
2026-023.0.0-rc.21仍 rc、无 stable；加 legacy API 兼容层
2026@scope 样式隔离 · create-qiankun 脚手架复苏迹象

结论：生产用 2.10.16；3.0 三年难产、rc 未 stable，别等。3.0 重构方向（可插拔 @qiankunjs/* 模块、原生吃 ESM、@scope 样式、CSP）清晰但未落地。详见演进与现状。

权威链接 ​

相关页 ​