微前端框架 qiankun 简明指南

一、什么是乾坤（qiankun）？

乾坤（qiankun）的核心作用是把多个独立开发、独立部署的前端应用（比如 Vue、React、Angular 项目）组合成一个完整的系统，让它们看起来像一个网站。

二、乾坤（qiankun）在干啥？

一句话说清楚：qiankun就是一个"前端项目大管家"，专门帮你把不同技术开发的网页拼成一个大系统。

举个简单的例子：

传统开发模式：

就像你要装修一栋大楼，必须一次性把墙面、地板、家具全搞完。想换个马桶？得把整栋楼拆了重装。

使用qiankun的模式：

你现在可以分别定制各个房间：卧室交给A公司（Vue项目），客厅交给B公司（React项目），厨房交给C公司（Angular项目）。qiankun就是那个总包工头，把这些独立装修好的房间完美拼接成一栋完整的别墅。

实际场景（房产系统）：

功能模块	谁开发	独立吗	qiankun管啥
二手房管理​	二手房团队（用Vue）	✅ 独立开发	用户点"二手房"时加载这个模块
新房管理​	新房团队（用React）	✅ 独立开发	用户点"新房"时加载这个模块
用户中心​	后台团队（用Angular）	✅ 独立开发	用户点"我的"时加载这个模块

结果是：用户感觉是在用一个完整的网站，但其实背后是三个完全独立的项目在运行。

三、乾坤怎么用？（两步搞定）

第1步：主应用配置（告诉乾坤"有哪些积木"）

在主项目的 main.js中，注册你要加载的子应用。

// 主应用 main.js
import { registerMicroApps, start } from 'qiankun';

// 注册子应用（告诉乾坤：我有这些积木块）
registerMicroApps([
  {
    name: '二手房管理', // 应用名称（积木块名字）
    entry: '//localhost:8081', // 子应用的访问地址（积木块的下载地址）
    container: '#subapp-container', // 页面上的一个 div 容器（放在页面哪个位置）
    activeRule: '/second-hand', // 当URL是/second-hand时，加载这个应用（访问 /house 时显示它）
  },
]);

// 启动 qiankun
start();

2. 子应用（二手房管理）配置

在子应用的 main.js中，导出三个生命周期函数（类似 App.vue 的 mounted、unmounted）。

// 子应用 main.js
import { createApp } from 'vue';
import App from './App.vue';

let app = null;

// 必须导出三个函数给乾坤调用
export async function bootstrap() {
  console.log('二手房应用启动');
}

export async function mount(props) {
  // 渲染到容器
  app = createApp(App);
  app.mount('#app'); // 注意：这里的 #app 是子应用自己的根节点
}

export async function unmount() {
  // 卸载应用
  app.unmount();
  app = null;
}

// 如果不是被乾坤加载，则独立运行
if (!window.__POWERED_BY_QIANKUN__) {
  createApp(App).mount('#app');
}

四、核心概念梳理

概念	解释	类比
主应用​	微前端架构的"外壳"或"基座"，负责加载和管理子应用	操作系统
子应用​	独立开发、独立部署的前端应用，可以是 Vue/React/Angular 等	安装在操作系统上的 App
路由匹配​	定义子应用在什么 URL 路径下被激活	网址导航
生命周期​	子应用暴露的 bootstrap、mount、unmount函数	App 的安装、启动、卸载
样式隔离​	qiankun 自动创建沙箱，隔离子应用的 CSS 和 JS	每个 App 在独立的"房间"运行

五、为什么要用乾坤（qiankun）？

场景	痛点	qiankun 解决方案
技术栈升级​	老项目是 Vue 2，新功能想用 Vue 3 或 React 18	新模块独立开发，老模块保留，通过 qiankun 整合
独立团队协作​	不同团队负责不同模块，发布节奏不同	子应用独立部署，互不影响
巨型应用拆分​	项目臃肿，构建慢，开发体验差	按业务拆分成多个子应用，并行开发

六、实际场景示例

假设你正在开发一个大型房产交易平台：

模块	技术栈	开发团队	部署地址
主框架​ (导航/登录)	Vue 3	基础架构组	https://main.com
二手房管理​	Vue 2	二手房业务组	https://second-hand.com
新房管理​	React 18	新房业务组	https://new-house.com
租赁管理​	Vue 3 + TypeScript	租赁业务组	https://rent.com

访问流程：

1. 用户打开 https://platform.com ，看到主框架。

2. 点击"二手房"，URL 变为 https://platform.com/second-hand 。

3. qiankun 检测到 activeRule:'/second-hand' ，动态加载 https://second-hand.com 的代码。

4. 二手房模块在主框架的 #subapp-container 容器中渲染。

七、注意事项

样式隔离：qiankun 默认开启 JS 沙箱，但 CSS 隔离需配合 Shadow DOM 或 CSS Modules 使用。

公共依赖 ：避免子应用重复打包 Vue、React 等库，可通过 externals或主应用提供。

通信规范 ：推荐使用 props或自定义事件通信，避免直接修改 window 对象。