一、引言

二、技术背景

1. 微前端的核心概念

• ​​独立开发与部署​​：每个子应用可独立开发（使用不同技术栈）、独立部署（如用户中心部署在 /user路径，订单管理部署在 /order路径），无需整体重新构建。
• ​​路由集成​​：主应用通过路由配置（如Vue Router）将特定路径（如 /user/*）委托给对应的子应用处理，子应用内部维护自己的路由规则（如 /user/profile）。
• ​​样式与生命周期隔离​​：避免子应用之间的CSS样式冲突（通过Shadow DOM或Scoped CSS），并控制子应用的加载、挂载和卸载时机（如路由切换时动态加载子应用）。
• ​​通信机制​​：主应用与子应用、子应用之间可通过全局事件总线（如 window.postMessage）或状态管理库（如Vuex/Pinia）共享数据（如用户登录状态）。

2. qiankun框架的核心能力

• ​​应用注册与路由匹配​​：主应用通过 registerMicroApps注册子应用（指定子应用的入口URL、激活路由规则），qiankun根据当前URL自动匹配并加载对应的子应用。
• ​​生命周期钩子​​：子应用需暴露 bootstrap（初始化）、mount（挂载）、unmount（卸载） 三个生命周期函数，qiankun在子应用加载/卸载时调用这些函数，确保资源正确初始化和清理。
• ​​样式隔离​​：通过动态创建 <style>标签的隔离策略（或Shadow DOM），防止子应用的CSS污染主应用或其他子应用。
• ​​预加载与缓存​​：支持子应用的预加载（提前下载资源）和缓存机制（减少重复加载时间），提升用户体验。

三、应用使用场景

1. 企业级后台管理系统

2. 电商平台的模块化拆分

3. 跨框架遗留系统迁移

4. 多租户SaaS应用

四、不同场景下详细代码实现

场景1：基础集成（Vue主应用 + Vue子应用）

4.1 主应用配置（Vue 3 + qiankun）

4.1.1 安装依赖

npm install qiankun --save

4.1.2 主应用路由配置（router/index.js）

// src/router/index.js
import { createRouter, createWebHistory } from 'vue-router';

const routes = [
  {
    path: '/',
    name: 'Home',
    component: () => import('../views/Home.vue'), // 主应用的首页
  },
  {
    path: '/sub-app/*', // 将 /sub-app 及其子路径委托给子应用
    name: 'SubApp',
    component: () => import('../components/SubAppWrapper.vue'), // 子应用容器组件
  },
];

const router = createRouter({
  history: createWebHistory(),
  routes,
});

export default router;

4.1.3 主应用入口（main.js） - 注册子应用

// src/main.js
import { createApp } from 'vue';
import App from './App.vue';
import router from './router';
import { registerMicroApps, start } from 'qiankun';

// 注册子应用
registerMicroApps([
  {
    name: 'sub-vue-app', // 子应用唯一标识
    entry: '//localhost:7101', // 子应用的开发服务器地址（生产环境替换为真实URL）
    container: '#subapp-container', // 子应用挂载的DOM节点（在SubAppWrapper.vue中定义）
    activeRule: '/sub-app', // 激活路由规则（当URL匹配/sub-app时加载子应用）
  },
]);

// 启动qiankun
start();

createApp(App).use(router).mount('#app');

4.1.4 子应用容器组件（SubAppWrapper.vue）

<!-- src/components/SubAppWrapper.vue -->
<template>
  <div id="subapp-container">
    <!-- 子应用的内容将挂载到此div中 -->
  </div>
</template>

<script setup>
// 无需额外逻辑，qiankun会自动将子应用渲染到 #subapp-container
</script>

4.2 子应用配置（Vue 3）

4.2.1 子应用入口（main.js） - 暴露生命周期函数

// 子应用入口文件（src/main.js）
import { createApp } from 'vue';
import App from './App.vue';
import router from './router';

let instance = null;

// 子应用的生命周期函数
function render(props = {}) {
  const { container } = props; // qiankun传递的挂载容器（来自主应用的 #subapp-container）
  instance = createApp(App);
  instance.use(router);
  instance.mount(container ? container.querySelector('#app') : '#app'); // 挂载到子应用的根节点
}

// 独立运行时（非qiankun环境，如本地开发直接访问子应用）
if (!window.__POWERED_BY_QIANKUN__) {
  render();
}

// 暴露给qiankun的生命周期钩子
export async function bootstrap() {
  console.log('[子应用] bootstrap');
}

export async function mount(props) {
  console.log('[子应用] mount', props);
  render(props); // 挂载子应用
}

export async function unmount() {
  console.log('[子应用] unmount');
  if (instance) {
    instance.unmount();
    instance = null;
  }
}

4.2.2 子应用路由配置（router/index.js）

// 子应用路由（src/router/index.js）
import { createRouter, createWebHistory } from 'vue-router';

const routes = [
  {
    path: '/', // 子应用的根路径（对应主应用的 /sub-app）
    name: 'SubHome',
    component: () => import('../views/SubHome.vue'),
  },
  {
    path: '/detail', // 子应用的子路径（对应主应用的 /sub-app/detail）
    name: 'SubDetail',
    component: () => import('../views/SubDetail.vue'),
  },
];

const router = createRouter({
  history: createWebHistory('/sub-app'), // 关键：子应用的路由base需与主应用的activeRule匹配
  routes,
});

export default router;

4.2.3 子应用根组件（App.vue）

<!-- 子应用根组件（src/App.vue） -->
<template>
  <div id="app">
    <router-view/>
  </div>
</template>

4.3 原理解释

• ​​主应用​​：通过 registerMicroApps注册子应用，指定子应用的入口URL（entry）、激活路由规则（activeRule: '/sub-app'）和挂载容器（container: '#subapp-container'）。当用户访问 /sub-app时，qiankun动态加载子应用的入口文件（//localhost:7101），并调用子应用的 mount生命周期函数，将子应用渲染到主应用指定的DOM节点中。
• ​​子应用​​：通过暴露 bootstrap、mount、unmount生命周期函数，与主应用通信。子应用的路由配置需设置 history: createWebHistory('/sub-app')，确保子应用的路由路径（如 /detail）能正确匹配主应用的 /sub-app/detail。

场景2：跨技术栈集成（Vue主应用 + React子应用）

4.4 主应用配置（与场景1类似，仅修改注册信息）

// src/main.js
registerMicroApps([
  {
    name: 'react-sub-app',
    entry: '//localhost:3001', // React子应用的开发服务器地址
    container: '#react-sub-container',
    activeRule: '/react-sub',
  },
]);

// 子应用容器组件（ReactSubWrapper.vue）
<template>
  <div id="react-sub-container"></div>
</template>

4.5 React子应用配置（关键点）

• ​​暴露生命周期​​：在React项目的入口文件（如 src/index.js）中，通过 ReactDOM.render的回调暴露 mount/unmount函数（需使用qiankun提供的 loadable或手动适配）。
• ​​路由base​​：React Router的 basename需设置为 /react-sub（与主应用的 activeRule匹配）。

// src/index.js (React)
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';
import { BrowserRouter } from 'react-router-dom';

let root = null;

function render(props) {
  const { container } = props;
  root = ReactDOM.createRoot(container.querySelector('#root'));
  root.render(
    <BrowserRouter basename="/react-sub">
      <App />
    </BrowserRouter>
  );
}

// 独立运行时
if (!window.__POWERED_BY_QIANKUN__) {
  render({ container: document.getElementById('root') });
}

// 暴露生命周期
export async function bootstrap() { console.log('React子应用 bootstrap'); }
export async function mount(props) { render(props); }
export async function unmount() { 
  if (root) { root.unmount(); root = null; }
}

五、原理解释

1. 微前端路由集成的核心流程

1. ​​主应用路由匹配​​：用户访问主应用的特定路径（如 /sub-app），主应用的Vue Router检测到该路径匹配 activeRule（注册子应用时指定的规则）。
2. ​​子应用加载​​：qiankun根据子应用的 entryURL（如 //localhost:7101），动态下载子应用的入口文件（通常是打包后的JS Bundle）。
3. ​​生命周期触发​​：子应用加载完成后，qiankun依次调用子应用的 bootstrap（初始化）、mount（挂载）生命周期函数，将子应用渲染到主应用指定的DOM容器（如 #subapp-container）中。
4. ​​子应用路由接管​​：子应用内部的路由（如Vue Router或React Router）根据当前URL（如 /sub-app/detail）渲染对应的组件，实现路由嵌套。
5. ​​卸载与清理​​：当用户离开 /sub-app路径时，qiankun调用子应用的 unmount生命周期函数，清理子应用的资源（如卸载组件、移除事件监听）。

2. 关键技术点

• ​​路由委托​​：主应用通过 activeRule将特定路径的渲染权交给子应用，子应用内部维护独立的路由规则（避免与主应用路由冲突）。
• ​​样式隔离​​：qiankun默认通过动态创建 <style>标签的策略隔离子应用的CSS（防止样式污染），也可配置Shadow DOM实现更强隔离。
• ​​通信机制​​：主应用与子应用可通过 window.dispatchEvent和 window.addEventListener传递全局事件（如用户登录状态变更），或使用状态管理库（如Vuex/Pinia）共享数据。

六、核心特性

七、原理流程图及原理解释

原理流程图（微前端路由集成执行流程）

+-----------------------+       +-----------------------+       +-----------------------+
|  用户访问主应用       |       |  主应用路由匹配       |       |  qiankun加载子应用    |
|  (如 /sub-app)        | ----> |  (activeRule匹配)     | ----> |  (动态下载入口文件)   |
+-----------------------+       +-----------------------+       +-----------------------+
          |                             |                             |
          |  触发子应用挂载     |  调用子应用生命周期   |  渲染子应用到容器     |
          |  (路由委托)         |  (bootstrap/mount)    |  (指定DOM节点)        |
          |----------------------->|----------------------->|                     |
          |                             |                             |  子应用路由接管       |
          |                             |                             |  (内部路由匹配)       |
          v                             v                             v
+-----------------------+       +-----------------------+       +-----------------------+
|  子应用渲染完成       |       |  用户交互（如点击)    |       |  子应用内部路由切换   |
|  (如 /sub-app/detail) |       |  触发子应用组件更新   |       |  (独立于主应用路由)   |
+-----------------------+       +-----------------------+       +-----------------------+
          |                             |                             |
          |  用户离开 /sub-app  |  调用子应用生命周期   |  清理子应用资源       |
          |  (路由切换)         |  (unmount)            |  (卸载组件/事件)      |
          |----------------------->|----------------------->|                     |
          v                             v                             v
+-----------------------+       +-----------------------+       +-----------------------+
|  主应用显示其他内容   |       |  子应用已卸载         |       |  资源释放完成         |
+-----------------------+       +-----------------------+       +-----------------------+

原理解释

1. ​​用户交互​​：用户访问主应用的 /sub-app路径，主应用的Vue Router检测到该路径匹配注册的子应用规则（activeRule: '/sub-app'）。
2. ​​子应用加载​​：qiankun根据子应用的入口URL（如 //localhost:7101），动态下载子应用的JS Bundle（通常是通过Webpack打包的Vue/React应用）。
3. ​​生命周期执行​​：子应用加载完成后，qiankun依次调用 bootstrap（初始化全局配置）、mount（挂载子应用到主应用指定的DOM容器），子应用内部的路由（如Vue Router）根据当前URL（如 /sub-app/detail）渲染对应的组件。
4. ​​路由嵌套​​：子应用的内部路由（如 /detail）与主应用的路由（如 /sub-app）组合成完整路径（/sub-app/detail），实现路由的层级化管理。
5. ​​卸载清理​​：当用户离开 /sub-app路径时，qiankun调用子应用的 unmount生命周期函数，卸载子应用的组件、移除事件监听，释放内存资源。

八、环境准备

1. 开发环境

• ​​工具​​：Vue CLI（或Vite） + qiankun（主应用），Create React App（或Vite） + qiankun（子应用，如React场景）。
• ​​依赖​​：主应用安装 qiankun（npm install qiankun），子应用无需额外依赖（仅需暴露生命周期函数）。
• ​​服务器​​：主应用和子应用需运行在不同的端口（如主应用 localhost:8080，子应用 localhost:7101），或通过代理解决跨域问题。

2. 生产环境部署

• ​​静态托管​​：主应用和子应用可分别部署到不同的服务器（如Nginx、Vercel），或通过Docker容器化部署。
• ​​跨域配置​​：若主应用和子应用部署在不同域名下，需配置CORS（跨域资源共享）或使用反向代理（如Nginx的 proxy_pass）。

九、实际详细应用代码示例实现

完整代码结构（基于场景1：Vue主应用 + Vue子应用）

• ​​主应用​​：包含路由配置（/sub-app委托给子应用）、qiankun注册逻辑、子应用容器组件。
• ​​子应用​​：暴露生命周期函数（bootstrap/mount/unmount）、路由配置（base: '/sub-app'）、根组件。

1. 创建主应用（Vue 3）和子应用（Vue 3），分别启动开发服务器（主应用 8080，子应用 7101）。
2. 在主应用中注册子应用（指定 entry: '//localhost:7101'和 activeRule: '/sub-app'）。
3. 访问主应用的 /sub-app路径，观察子应用的内容是否正确加载和渲染。

十、运行结果

正常情况（集成生效）

• ​​主应用​​：访问 /显示主应用的首页，访问 /sub-app显示子应用的内容（如“子应用首页”）。
• ​​子应用​​：独立维护自己的路由（如 /sub-app/detail显示“子应用详情页”），与主应用的路由无缝嵌套。
• ​​样式隔离​​：子应用的CSS样式不会影响主应用，主应用的样式也不会污染子应用。

异常情况（集成失败）

• ​​子应用未加载​​：检查主应用的 entryURL是否正确（如子应用服务器是否启动），或浏览器控制台是否有跨域错误（需配置CORS）。
• ​​路由不匹配​​：确认子应用的路由 base与主应用的 activeRule一致（如子应用 base: '/sub-app'对应主应用 /sub-app/*）。

十一、测试步骤及详细代码

测试场景1：验证子应用加载

1. ​​步骤​​：
   • 启动主应用和子应用（分别运行在 8080和 7101端口）。
   • 访问主应用的 /sub-app路径，观察浏览器控制台是否输出子应用的生命周期日志（如 [子应用] mount）。
   • 检查页面是否显示子应用的内容（如子应用的根组件渲染的文本）。
2. ​​预期结果​​：
   • 子应用成功加载，生命周期函数按顺序执行（bootstrap→ mount），内容正确渲染。

测试场景2：验证路由嵌套

1. ​​步骤​​：
   • 访问主应用的 /sub-app/detail路径（子应用的子路由），观察是否显示子应用的详情页组件。
   • 点击子应用内的导航链接（如 /sub-app/profile），检查是否正常切换组件。
2. ​​预期结果​​：
   • 子应用的内部路由（如 /detail）与主应用的 /sub-app组合成完整路径，路由切换流畅。

十二、部署场景

1. 静态托管（如Nginx）

• ​​主应用​​：部署到Nginx服务器（如 http://example.com），配置代理将 /sub-app的请求转发到子应用的服务器（如 http://sub-app.example.com:7101）。
• ​​子应用​​：部署到独立的服务器或容器，确保入口URL（如 http://sub-app.example.com:7101）可被主应用访问。

2. 生产环境配置

• ​​跨域处理​​：若主应用和子应用部署在不同域名下，需在Nginx中配置CORS头（如 Access-Control-Allow-Origin: *），或使用反向代理避免跨域问题。
• ​​HTTPS支持​​：生产环境建议使用HTTPS，确保子应用的入口URL（entry）为HTTPS协议，避免浏览器安全限制。

十三、疑难解答

问题1：子应用未加载（404或空白）

问题2：路由不匹配（子应用内容未显示）

问题3：样式冲突（子应用样式影响主应用）

十四、未来展望

1. 技术趋势

• ​​更轻量的运行时​​：qiankun未来可能进一步优化子应用的加载性能（如按需加载子应用的路由模块）。
• ​​跨框架通信增强​​：提供更便捷的主应用与子应用通信机制（如基于Redux的全局状态共享）。
• ​​Serverless集成​​：结合Serverless架构（如AWS Lambda），子应用可按需动态部署和加载，降低运维成本。

2. 挑战

• ​​复杂状态管理​​：多子应用之间的全局状态（如用户登录信息）同步需依赖统一的存储方案（如Redis或JWT）。
• ​​性能监控​​：微前端应用的性能分析（如子应用加载时间、路由切换耗时）需要更精细的工具支持。

十五、总结