Framework Qiankun 用微前端拆分大型前端应用

一、项目介绍

前端项目长到某个体量，就会撞上一堵墙：代码耦合、发布牵一发动全身、新人上手要读三个月的代码。想拆开，又怕引入一堆新问题——子应用怎么发布静态资源、主应用怎么加载、样式和 JS 会不会互相污染、公共依赖要不要重复打包、性能怎么兜。

Qiankun（乾坤）正是为这些问题而生。它基于 single-spa，提供了一套完整可落地的微前端方案：子应用通过导出生命周期函数被主应用加载与卸载，JS 沙箱隔离各应用的全局变量，样式隔离避免污染，公共依赖与通信机制一并给出。

它出自蚂蚁团队的内部实践，最初正是为了解决分布式团队协作开发的混乱。3.0 版本目前仍在开发中，官方建议先看 Roadmap；需要 2.x 稳定文档可访问 v2.qiankun.umijs.org。目前 star 数约 1.67 万。

微前端的难点从来不在"把几个应用塞进一个页面"这种表面工作，真正难的是隔离与治理。Qiankun 在这两处下了重注。

JS 沙箱基于 Proxy 与作用域劫持实现。子应用的全局变量被限制在自己的作用域内，对 window 的修改不会外泄到主应用，也不会影响其他子应用。样式隔离则处理 CSS 的全局污染问题——子应用的样式规则被限定在自身容器内，避免互相覆盖。这两件事在小规模演示里看不出来，等到主应用与四五个子应用共存时，就会决定这套方案能不能落地。

公共依赖是个现实问题。qiankun 提供了依赖提取与共享方案：把 React、Vue 这类公共库从子应用构建产物里提取出来统一加载，避免同一个库在每个子应用里各打一份，包体积立刻小一大截。

通信机制则覆盖了子应用与主应用、子应用与子应用之间的几种典型模式：props 传参、事件总线、以及基于 qiankun 的全局状态方案。主应用注册子应用时可以附带 props，子应用在 mount 阶段接收。

它基于 single-spa 构建，但走的是另一条路线——single-spa 偏底层、需要自己组装较多东西，qiankun 把样式隔离、依赖方案、通信这些工程细节都补齐了。

二、项目基本信息

三、核心优势

• 完整覆盖微前端落地难点：加载、沙箱隔离、样式隔离、公共依赖、通信
• JS 沙箱基于 Proxy 与 with 作用域劫持，各子应用的全局变量互不干扰
• 不依赖框架，React、Vue、Angular 等任意技术栈的子应用都能接入
• 子应用可独立开发与独立部署，改一块不必整体发版
• 提供 lifecycle 生命周期钩子，加载、挂载、更新、卸载均可拦截
• 官方仓库带完整示例工程，React 与 Vue 两种主应用可直接对照学习
• 生命周期钩子（bootstrap / mount / update / unmount）可在关键节点插入自定义逻辑，便于做埋点与资源清理
• 子应用可独立开发与独立部署，配合 CI 各子应用发版节奏互不牵连
• 官方仓库提供 React 与 Vue 两套主应用示例，改造现有项目时可直接对照
• 基于 single-spa 生态，与相关工具链的兼容性与社区经验可复用

四、适用场景

适合多团队并行开发同一个前端产品、单一应用已经难以维护的团队；也适合需要把遗留系统分阶段拆分的组织。技术栈混杂的团队用它的收益最明显。

用不用微前端，取决于你的组织结构而不是技术偏好。如果一个团队维护一个应用，普通的前端架构就够；如果五个团队同时改同一个页面，拆分的收益才明显——而且真正的收益是"发布解耦"，改一块不必整体发版。

成本也要算清楚：qiankun 带来的额外概念（生命周期、路由配合、样式隔离规则、跨应用通信）需要团队理解与约定，公共依赖的版本协调也需要专人负责。如果团队规模小、变动频繁，引入微前端可能得不偿失。

版本选择上要注意：3.0 正在开发中，README 顶部有明确警告。当前要上生产建议用 2.x，其文档在独立的 v2 域名。评估时可以先看一眼 Roadmap，确认关键特性是否已覆盖你的场景。

它支持 React、Vue、Angular 等任意技术栈的子应用，这意味着你可以按团队既有偏好分批迁移，而不是强制统一框架。

如果你正被同类问题反复绊住——要么是人肉重复劳动没完，要么是工具装不上跑不通、要么是产出的结果根本没法用——那这个项目值得先花十分钟装一遍试试。

五、安装教程

当前最新版本 v2.10.16。下面是可直接执行的安装方式：

# 在已有主应用工程中引入
npm i qiankun@rc

# 或从源码启动官方示例（pnpm workspace）
git clone https://github.com/umijs/qiankun.git
cd qiankun
pnpm install
pnpm start:example
# React 主应用示例：http://localhost:7099
# Vue 主应用示例：http://localhost:7105

常见报错与处理：依赖缺失时先确认运行时版本（Node、Python、Rust、PHP 等）是否满足项目要求；网络超时多半是镜像或代理问题，可换源重试；权限类报错请检查当前账号是否已登录对应平台，以及脚本是否需要管理员权限执行。

六、使用示例

下面这段是可以直接参照的真实用法：

// 主应用：注册并启动子应用
import { registerMicroApps, start } from 'qiankun';

registerMicroApps([
  {
    name: 'app-vue',
    container: '#subapp-container',
    props: { message: 'hello from main app' },
    activeRule: '/vue',
  },
]);

start({
  sandbox: { experimentalStyleIsolation: true },
  prefetch: 'all',
});

// 子应用：导出三个生命周期钩子
export async function bootstrap() {}
export async function mount(props) {
  render(props);
}
export async function unmount() {
  destroy();
}

七、常见问题

问：qiankun 3.0 和 2.x 怎么选？答：3.0 正在积极开发中，具体进度看官方 Roadmap；需要现在就上生产，建议用 2.x 并参考 v2.qiankun.umijs.org 的文档。

问：子应用必须同源吗？答：不一定，跨域子应用需要配置相应的 CORS 与资源加载策略，官方文档有专门章节说明。

问：公共依赖怎么处理？答：框架提供了依赖提取与共享方案，避免同一份库在多个子应用里重复打包。

问：接入前要改造多少东西？答：核心改动是让子应用导出 bootstrap / mount / unmount 三个生命周期函数，并调整入口文件，业务代码本身通常不需要重写。

问：改造现有项目的工作量多大？答：主要是调整入口文件、导出三个生命周期函数并把渲染逻辑挂到 mount/unmount 上，业务代码通常不需要重写。

问：子应用之间怎么通信？答：主应用注册时可通过 props 向子应用传参，也可用事件总线做跨应用通知。

以上是实际使用中最常被问到的几个问题。若遇到文档未覆盖的情况，可以先翻项目的 Issues 与 Discussions 区，那里有更多真实踩坑记录。

八、总结

Qiankun 在把一类应用的写法标准化这件事上做到了足够扎实的程度：它不追求大而全，而是把一个具体环节做透，让原本要靠人盯的流程变成可以交给工具执行的流程。

从上面的安装步骤和使用示例可以看出，它的接入成本并不高：一条命令装好，按提示完成配置，然后就能把它放进你原有的工作流里。如果你正在被同类问题困扰，不妨先在自己的一小块任务上试一轮，确认顺手了再推广到日常流程中。