umijs /qiankun
📦 🚀 Blazing fast, simple and complete solution for micro frontends.
★ 16,703⑂ 2,053👁 220⑃ 931● 2,096▤ 147
+0
日增长
16,703
stars
2,053
forks
220
watchers
931
prs
2,096
issues
147
releases
README
文档 ·
快速上手 ·
在线示例 ·
路线图
English · 简体中文
qiankun(乾坤)
[!WARNING]
🚧 qiankun 3.0 正在密集开发中,进展见路线图。在找 qiankun 2.x?它的文档在 v2.qiankun.umijs.org。
乾为天,坤为地,乾坤即宇宙——正如它的名字,qiankun 可以承载一切。
qiankun 是一个基于 single-spa 的微前端框架,帮助你和你的团队构建面向下一代的企业级 Web 应用。
🤔 为什么做 qiankun
先回顾一下「微前端」的定义:
一种由多个团队、以不同 JavaScript 技术栈协作构建现代 Web 应用的技术手段与策略。—— Micro Frontends
qiankun 诞生于我们内部大规模分布式团队协作陷入混乱的时期——微前端要解决的每一个问题,我们都真实遇到过,于是它自然而然成为了我们解法的一部分。
这条路并不好走,能踩的坑我们几乎都踩过一遍。随便举几个:
- 微应用的静态资源以什么形式发布?
- 框架怎样把一个个独立的微应用集成起来?
- 如何确保微应用之间彼此隔离(开发独立、部署独立),并且运行时相互沙箱化?
- 性能问题怎么办?公共依赖怎么处理?
- ……
在解决完这些微前端的通用问题、经过大量打磨和验证之后,我们把方案中最小可用的框架部分提取出来,命名为 qiankun——取其可承载一切之意。此后它成为了我们生产环境中数百个应用的基石,我们决定将它开源,让大家少走弯路。
一句话总结:qiankun 可能是你见过最完善的微前端解决方案🧐。
✨ 核心能力
qiankun 继承了 single-spa 的基本盘——独立部署、按需加载、主应用不限制微应用技术栈——并补齐了真实产品所需的那些部分:
- 📄 HTML Entry —— 接入一个 URL 即可,不需要维护资源清单。HTML Entry 边下载边流式写入容器,其中的 HTML 可在响应结束前逐步呈现。
- 🧳 JS 沙箱 —— 默认启用 window 和 document 的 Proxy 隔离膜视图。全局属性写入保存在应用内,并追踪定时器、事件监听和动态资源等常见副作用,卸载时清理已追踪的资源。
- 📦 原生 ESM —— 微应用以真正的模块方式执行,经隔离膜路由并配合动态注入的 import map。动态 import() 可用,Vite 开发服务器也可以直接接入。
- 🛡 样式隔离 —— 基于 CSS @scope 规则的运行时作用域方案(可选开启),外链样式表同样覆盖。不需要改写你的 CSS,也没有 Shadow DOM 的额外负担。
- ⚡ 自动预加载 —— 流式解析 HTML Entry 时,自动发现并预加载其中的脚本和样式。应用激活前的预取 API prefetchApps 仍为兼容旧代码而保留,但已废弃。
- 🧩 UI 绑定 —— 面向 React 和 Vue 的 组件,自带加载态和错误边界插槽,微应用用起来就像一个普通组件。
- 🔧 构建插件 —— 一个插件同时支持 webpack 4/5 与 Vite,自动为相应脚本添加 entry 属性、修正产物库配置,替代过去手写的样板配置。
- 🔬 独立沙箱 —— @qiankunjs/sandbox 可以脱离微前端框架单独使用,用于隔离可信第三方脚本的全局写入并管理常见副作用。
🚀 快速上手
[!NOTE]
v3 目前发布在 rc 标签上,npm 的 latest 仍指向 2.x。安装时需显式指定 @rc。
最快的方式是使用 agent skill——安装后,让你的 coding agent(Claude Code、Cursor 等)生成配置完整的主应用或微应用:
shell
npx skills add umijs/qiankun
也可以在现有主应用中直接安装:
shell
npm i qiankun@rc
把微应用加载到任意容器元素中,并保存返回的实例句柄用于卸载:
ts
import { loadMicroApp } from 'qiankun';
const container = document.getElementById('subapp-container');
if (!container) throw new Error('subapp-container not found');
const microApp = loadMicroApp({
name: 'react-app',
entry: '//localhost:7100',
container,
});
// 页面区域销毁前卸载微应用:
await microApp.unmount();
如果微应用的激活状态完全由 URL 决定,也可以使用路由驱动的 registerMicroApps + start 作为另一种编排方式。
微应用侧只需导出三个生命周期函数:
ts
let root;
export async function bootstrap() {}
export async function mount(props: { container: HTMLElement }) {
root = render(props.container);
}
export async function unmount() {
root.unmount();
}
约定就这么多。各技术栈所需的构建配置见快速上手。
💿 示例
所有示例都已部署在 examples.qiankunjs.com,可直接在线体验:两个主应用外壳(React 与 Vue)加载同一组四个微应用,全部开启 JS 沙箱和样式隔离,另有一个独立沙箱实验室。每个微应用都带有「隔离实验室」,直观演示沙箱到底隔离了什么:全局变量、泄漏的定时器、注入的样式。外壳支持中英文切换,语言选择会作为 prop 传递给微应用——它们通过 update 生命周期重新渲染,而不是重新挂载。
本地运行:
shell
git clone https://github.com/umijs/qiankun.git
cd qiankun
pnpm install
pnpm start:example
该命令会构建 workspace 内的所有包并并行启动全部示例应用——React 外壳在 http://localhost:7099,Vue 外壳在 http://localhost:7105。各应用分别演示什么见 examples/README.md。
!
📦 包一览
| 包名 | 版本(点击查看更新日志) | 说明 |
| --- | :-- | --- |
| qiankun | | 框架本体:registerMicroApps、loadMicroApp、start、prefetch |
| @qiankunjs/loader | | 流式 HTML Entry 加载器 |
| @qiankunjs/Top issues
#1257想问一下,未来是否考虑支持 vite58 comments · 2021-02-05#1865主应用和子应用都是用Vue3+VueRouter4,点击主应用中菜单进行router.push,对应同一个activeRule的子应用来回切换,会重复创建子应用实例39 comments · 2021-12-10#1777分享你的 demo [ Share your demo ]38 comments · 2021-10-23#442[RFC] 2.0 文档计划31 comments · 2020-04-16#1963[Feature Request] 关于样式隔离26 comments · 2022-02-13#830[Feature Request] 关于子系统的热重载问题25 comments · 2020-08-06#1453官网的angular配置子应用报错:Expected to not be in Angular Zone, but it is!21 comments · 2021-05-18#452如何使用angular作为基座21 comments · 2020-04-17
Discussions
#3119Academic Survey: Impact of Micro-frontend Adoption in Companies (5–7 min)0 comments · 2026-03-02#3118Academic Survey: Impact of Micro-frontend Adoption in Companies (5–7 min)0 comments · 2026-03-02#3087nuxt3 嵌入qiankun1 comments · 2025-08-26#3085基于 2.10.16 tag 执行 yarn examples:install 报错0 comments · 2025-08-19#3069目前乾坤还在维护吗?感觉很久没有新消息了。1 comments · 2025-05-29#3068多个大屏项目可以接入qiankun吗?0 comments · 2025-05-21#3065【请求帮助】初始化主应用时,activeRule并不满足,如何去加载子应用,或者满足activeRule 并不需要去跳转子应用的页面0 comments · 2025-05-08#3063发到线上后,vite子应用无法加载0 comments · 2025-05-06
Latest release
v2.10.16 v2.10.16 2023-11-15- ⚡️ remove object spread operator for faster performance in big array iterator (2812) e75952fa https://github.com/kuitos/qiankun/compare/v2.10.15...v2.10.16