前端微服务框架乾坤（Qiankun）实战指南

前端微服务框架乾坤（Qiankun）实战指南

一、初识乾坤：为什么选择微前端？

在传统单体前端架构中，随着业务复杂度增加，代码臃肿、协作困难、部署效率低等问题愈发突出。微前端通过将项目拆分为多个独立自治的微应用，解决了这些问题：

• 技术栈无关：支持 Vue、React、Angular 等框架混合开发
• 独立部署：各团队可独立开发、测试、发布
• 渐进升级：允许逐步重构旧系统
• 动态加载：按需加载减少首屏耗时

乾坤（Qiankun） 是蚂蚁金服基于 Single-SPA 优化的微前端框架，提供开箱即用的基座能力，本文将从基础到实战带你掌握其核心用法。

---

二、环境搭建与基础配置

1. 主应用初始化

# 创建主应用（Vue 3）
vue create main-app
cd main-app
# 安装乾坤依赖
npm install qiankun --save

2. 主应用配置（main.js）

import { createApp } from 'vue'
import App from './App.vue'
import { registerMicroApps, start } from 'qiankun'

const app = createApp(App)
app.mount('#app')

// 注册子应用
registerMicroApps([
  {
    name: 'vueApp', // 子应用名称
    entry: '//localhost:7100', // 子应用入口地址
    container: '#subapp-container', // 挂载节点
    activeRule: '/vue', // 触发路由规则
    props: { msg: '来自主应用的数据' } // 传递参数
  },
  {
    name: 'reactApp',
    entry: '//localhost:7101',
    container: '#subapp-container',
    activeRule: '/react'
  }
])

// 启动乾坤
start()

3. 主应用模板（App.vue）

<template>
  <div id="app">
    <h1>主应用</h1>
    <nav>
      <router-link to="/vue">Vue 子应用</router-link>
      <router-link to="/react">React 子应用</router-link>
    </nav>
    <div id="subapp-container"></div>
  </div>
</template>

---

三、子应用开发与接入

1. Vue 子应用配置

（1）创建子应用

# 创建 Vue 子应用
vue create vue-app
cd vue-app
# 安装依赖
npm install qiankun --save

（2）修改 main.js

import { createApp } from 'vue'
import App from './App.vue'
import routes from './routes' // 自定义路由

let instance = null

function render(props = {}) {
  const { container, routerBase, msg } = props
  const app = createApp(App)
  
  // 动态配置路由
  const router = createRouter({
    history: createWebHistory(routerBase),
    routes: routes.map(route => ({
      ...route,
      path: `${routerBase}${route.path}` // 拼接基路径
    }))
  })
  
  app.use(router)
  app.mount(container ? container.querySelector('#app') : '#app')
  console.log('主应用传来的数据:', msg)
}

// 独立运行时直接渲染
if (!window.__POWERED_BY_QIANKUN__) {
  render()
}

// 导出生命周期函数
export async function bootstrap() {
  console.log('Vue 子应用启动')
}
export async function mount(props) {
  console.log('Vue 子应用挂载')
  render(props)
}
export async function unmount() {
  instance.unmount()
  instance = null
  console.log('Vue 子应用卸载')
}

（3）配置 vue.config.js

const { name } = require('./package')

module.exports = {
  devServer: {
    port: 7100,
    headers: { 'Access-Control-Allow-Origin': '*' }
  },
  configureWebpack: {
    output: {
      library: `${name}-[name]`,
      libraryTarget: 'umd',
      jsonpFunction: `webpackJsonp_${name}`
    }
  }
}

---

2. React 子应用配置

（1）创建子应用

# 创建 React 子应用
npx create-react-app react-app
cd react-app
# 安装依赖
npm install qiankun --save

（2）修改 src/index.js

import React from 'react'
import ReactDOM from 'react-dom'
import App from './App'

let instance = null

function render(props) {
  const { container, routerBase } = props || {}
  ReactDOM.render(<App basename={routerBase} />, container ? container.querySelector('#root') : document.getElementById('root'))
}

// 独立运行时渲染
if (!window.__POWERED_BY_QIANKUN__) {
  render()
}

// 导出生命周期函数
export async function bootstrap() {
  console.log('React 子应用启动')
}
export async function mount(props) {
  console.log('React 子应用挂载')
  render(props)
}
export async function unmount() {
  ReactDOM.unmountComponentAtNode(instance.container.querySelector('#root'))
  console.log('React 子应用卸载')
}

（3）配置 craco.config.js（解决 Single-SPA 兼容性）

const CracoAntDesignPlugin = require('craco-antd')

module.exports = {
  plugins: [
    {
      plugin: CracoAntDesignPlugin,
      options: {
        customizeTheme: {
          '@primary-color': '#1DA57A'
        }
      }
    }
  ]
}

---

四、核心特性解析

1. 沙箱机制与样式隔离

• JS 沙箱：每个子应用运行在独立的沙箱环境中，避免全局变量污染
• 样式隔离：建议使用 Scoped CSS 或 CSS Modules，乾坤默认不处理 CSS 隔离

/* Vue 子应用示例 */
.button {
  background: #1da57a; /* 私有样式 */
}

2. 全局状态通信

// 主应用定义全局状态
import { initGlobalState } from 'qiankun'

const state = { user: 'Admin' }
const actions = initGlobalState(state)

actions.onGlobalStateChange((newState, prev) => {
  console.log('状态变更:', newState)
})

// 子应用获取状态
const [user] = useState(() => qiankun.getGlobalState().user)

3. 动态路由与预加载

// 主应用配置预加载
registerMicroApps([{
  name: 'vueApp',
  preLoad: true // 预加载子应用
}])

---

五、完整工作流程演示

1. 启动主应用 ：访问 http://localhost:8080，显示导航菜单
2. 加载子应用 ：
   • 点击 "Vue 子应用" → 加载 http://localhost:7100 的 Vue 应用
   • 点击 "React 子应用" → 加载 http://localhost:7101 的 React 应用
3. 调试验证 ：
   • 检查网络请求，确认子应用资源加载
   • 查看控制台生命周期日志（bootstrap → mount → unmount）
   • 验证样式隔离和数据通信

---

六、生产环境部署要点

1. 构建子应用：

   # Vue 子应用
   vue build --base=/vue/  # 设置资源路径前缀
   # React 子应用
   npm run build

2. 主应用配置 Nginx：

   server {
     listen 80;
     location / {
       root /path/to/main-app/dist;
       try_files $uri $uri/ /index.html;
     }
     location /vue/ {
       proxy_pass http://localhost:7100; # Vue 子应用地址
     }
     location /react/ {
       proxy_pass http://localhost:7101; # React 子应用地址
     }
   }

3. 跨域处理：确保子应用服务器允许主应用域名跨域访问

---

七、总结与扩展

优势	注意事项
技术栈解耦	需处理样式隔离
独立部署	需统一路由规划
渐进式重构	需注意全局状态管理

学习资源推荐：

• 乾坤官方文档
• 示例代码仓
• Micro Frontends 模式深度解析

通过本文，你可以掌握乾坤的核心用法，从基础配置到生产部署，逐步构建稳健的微前端架构。