umijs /qiankun

📦 🚀 Blazing fast, simple and complete solution for micro frontends.

★ 16,703⑂ 2,053👁 220⑃ 931● 2,096▤ 147
TypeScriptMITCreated 2019-05-15qiankun.umijs.org
TA的项目
下载:v2.10.16qiankun-2.10.16 ↓2.10.162023-11-15
+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

Discussions

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

Snapshot: 2026-11-16T09:23:14Z · Data license Apache-2.0 · JSON