在 qiankun 微前端架构中嵌入 Vue2 和 Vue3 微应用，包括主应用搭建、各微应用改造、集成配置及关键注意事项

原创 于 2025-11-28 17:20:11 发布 · 306 阅读 · 7 ·
CC 4.0 BY-SA版权
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
文章标签：

#前端 #架构

在 qiankun 微前端架构中嵌入 Vue2 和 Vue3 微应用，包括主应用搭建、各微应用改造、集成配置及关键注意事项。下面我会从基础到实战，一步步带你完成整个流程。

一、基础准备

1. qiankun 核心概念

qiankun 是基于 single-spa 封装的微前端框架，核心思想是主应用（基座）管理多个微应用（子应用），实现：

  • 微应用独立开发、独立部署
  • 主应用按需加载微应用
  • 应用间通信与样式隔离

2. 环境要求

  • Node.js >= 14
  • 主应用：Vue3（示例）
  • 微应用：Vue2、Vue3（分别改造）

二、主应用搭建（Vue3 + Webpack）

1. 创建主应用

# 创建 Vue3 主应用（Webpack 模板）
vue create main-app
cd main-app

2. 安装 qiankun

npm install qiankun --save

3. 主应用核心配置

(1) 准备挂载容器

在 src/App.vue 中添加微应用挂载节点：

<template>
  <div id="app">
    <nav>
      <router-link to="/">主应用</router-link> |
      <router-link to="/vue2-app">Vue2微应用</router-link> |
      <router-link to="/vue3-app">Vue3微应用</router-link>
    </nav>
    <!-- 微应用挂载容器 -->
    <div id="micro-app-container"></div>
    <router-view />
  </template>
(2) 注册并启动微应用

修改 src/main.js，注册微应用并启动 qiankun：

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

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

// 注册微应用
registerMicroApps([
  // Vue2 微应用配置
  {
    name: 'vue2-app', // 微应用唯一标识（需与微应用package.json name一致）
    entry: '//localhost:8081', // 微应用访问地址
    container: '#micro-app-container', // 挂载容器
    activeRule: '/vue2-app', // 激活路由规则
    props: { /* 向微应用传递的参数 */ }
  },
  // Vue3 微应用配置
  {
    name: 'vue3-app',
    entry: '//localhost:8082',
    container: '#micro-app-container',
    activeRule: '/vue3-app',
    props: { /* 向微应用传递的参数 */ }
  }
])

// 启动 qiankun（生产环境建议配置 sandbox: true 开启沙箱）
start({ sandbox: { strictStyleIsolation: true } })
(3) 主应用路由配置（可选）

修改 src/router/index.js，确保路由匹配激活规则：

import { createRouter, createWebHistory } from 'vue-router'
import Home from '../views/Home.vue'

const routes = [
  { path: '/', name: 'Home', component: Home },
  // 微应用占位路由（保证主应用路由不拦截微应用路径）
  { path: '/vue2-app/*', name: 'Vue2App', component: () => import('../views/MicroApp.vue') },
  { path: '/vue3-app/*', name: 'Vue3App', component: () => import('../views/MicroApp.vue') }
]

// 注意：主应用建议用 history 模式，微应用路由需与主应用协调
const router = createRouter({
  history: createWebHistory(process.env.BASE_URL),
  routes
})

export default router

三、Vue2 微应用改造

1. 创建 Vue2 微应用

vue create vue2-app # 选择 Vue2 模板
cd vue2-app

2. 核心改造步骤

(1) 配置 publicPath（动态适配）

在 vue.config.js 中添加：

const { defineConfig } = require('@vue/cli-service')
module.exports = defineConfig({
  // 关键：允许跨域（主应用加载微应用资源需要）
  devServer: {
    port: 8081, // 固定端口（与主应用配置一致）
    headers: {
      'Access-Control-Allow-Origin': '*'
    }
  },
  // 动态设置 publicPath（qiankun 会注入 __INJECTED_PUBLIC_PATH_BY_QIANKUN__ 变量）
  configureWebpack: {
    output: {
      library: `vue2-app-[name]`,
      libraryTarget: 'umd', // 输出格式为 UMD（支持qiankun加载）
      chunkLoadingGlobal: `webpackJsonp_vue2-app` // 防止 chunk 名称冲突
    }
  }
})
(2) 修改入口文件（导出生命周期函数）

修改 src/main.js，使其支持 qiankun 加载：

import Vue from 'vue'
import App from './App.vue'
import router from './router'

Vue.config.productionTip = false

let instance = null

// 微应用生命周期：挂载
function render(props = {}) {
  const { container } = props
  // 动态设置路由 base（与主应用 activeRule 一致）
  router.base = window.__POWERED_BY_QIANKUN__ ? '/vue2-app' : '/'
  
  instance = new Vue({
    router,
    render: h => h(App)
  }).$mount(container ? container.querySelector('#app') : '#app')
}

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

// 导出 qiankun 所需的生命周期函数
export async function bootstrap() {
  console.log('Vue2 微应用启动')
}

export async function mount(props) {
  console.log('Vue2 微应用挂载', props)
  render(props)
}

export async function unmount() {
  console.log('Vue2 微应用卸载')
  instance.$destroy()
  instance = null
}
(3) 路由配置适配

修改 src/router/index.js，设置路由模式为 history（与主应用一致）：

import Vue from 'vue'
import Router from 'vue-router'
import Home from '../views/Home.vue'

Vue.use(Router)

export default new Router({
  mode: 'history', // 关键：使用 history 模式
  routes: [
    { path: '/', name: 'Home', component: Home },
    { path: '/about', name: 'About', component: () => import('../views/About.vue') }
  ]
})

四、Vue3 微应用改造（分 Webpack/Vite 两种场景）

场景 1：Vue3 + Webpack 微应用

1. 创建应用
vue create vue3-app # 选择 Vue3 模板
cd vue3-app
2. 核心改造
  • 步骤 1：修改 vue.config.js（同 Vue2 微应用，仅端口改为 8082）
  • 步骤 2：修改入口文件 main.js：
import { createApp } from 'vue'
import App from './App.vue'
import router from './router'

let app = null

function render(props = {}) {
  const { container } = props
  router.base = window.__POWERED_BY_QIANKUN__ ? '/vue3-app' : '/'
  
  app = createApp(App)
  app.use(router).mount(container ? container.querySelector('#app') : '#app')
}

if (!window.__POWERED_BY_QIANKUN__) {
  render()
}

export async function bootstrap() {
  console.log('Vue3 微应用启动')
}

export async function mount(props) {
  console.log('Vue3 微应用挂载', props)
  render(props)
}

export async function unmount() {
  console.log('Vue3 微应用卸载')
  app.unmount()
  app = null
}

场景 2：Vue3 + Vite 微应用（主流方案）

qiankun 对 Vite 微应用的支持需额外适配，推荐使用 vite-plugin-qiankun 插件：

1. 创建 Vite 版 Vue3 应用
npm create vite@latest vue3-vite-app -- --template vue
cd vue3-vite-app
npm install
2. 安装适配插件
npm install vite-plugin-qiankun --save-dev
3. 配置 vite.config.js
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import qiankun from 'vite-plugin-qiankun'

export default defineConfig({
  plugins: [
    vue(),
    qiankun('vue3-vite-app', { // 微应用名称（与主应用注册的name一致）
      useDevMode: true
    })
  ],
  server: {
    port: 8083,
    cors: true, // 允许跨域
    origin: '//localhost:8083' // 配置 origin（解决资源加载问题）
  },
  base: '/vue3-app/' // 与主应用 activeRule 一致
})
4. 修改入口文件 main.js
import { createApp } from 'vue'
import App from './App.vue'
import router from './router'
import { renderWithQiankun, qiankunWindow } from 'vite-plugin-qiankun/dist/helper'

let app = null

function render(props = {}) {
  const { container } = props
  app = createApp(App)
  app.use(router).mount(container ? container.querySelector('#app') : '#app')
}

// 判断是否在 qiankun 环境中
if (!qiankunWindow.__POWERED_BY_QIANKUN__) {
  render()
}

// 注册 qiankun 生命周期
renderWithQiankun({
  bootstrap() {
    console.log('Vue3 Vite 微应用启动')
  },
  mount(props) {
    console.log('Vue3 Vite 微应用挂载', props)
    render(props)
  },
  unmount(props) {
    console.log('Vue3 Vite 微应用卸载')
    app.unmount()
    app = null
  }
})

五、启动与测试

  1. 启动主应用：cd main-app && npm run serve（默认端口 8080）
  2. 启动 Vue2 微应用：cd vue2-app && npm run serve（端口 8081）
  3. 启动 Vue3 微应用：cd vue3-app && npm run serve（端口 8082）
  4. 访问主应用 http://localhost:8080，点击导航栏链接即可加载对应微应用。

六、常见问题与解决方案

1. 微应用资源加载失败

  • 原因：跨域或 publicPath 配置错误
  • 解决：微应用开启 CORS（devServer.headers），动态设置 publicPath。

2. 样式冲突

  • 原因：主 / 微应用样式未隔离
  • 解决：主应用启动时开启 strictStyleIsolation: true，或微应用样式添加唯一前缀。

3. 路由冲突

  • 原因：主 / 微应用路由路径重叠
  • 解决：微应用路由 base 与主应用 activeRule 一致，主应用添加占位路由。

4. Vite 微应用白屏

  • 原因：Vite 资源加载机制与 qiankun 不兼容
  • 解决：使用 vite-plugin-qiankun 插件，配置 origin 和 base。

总结

  1. 主应用核心：通过 registerMicroApps 注册微应用，start 启动 qiankun，需准备挂载容器和激活路由。
  2. 微应用改造关键：导出 bootstrap/mount/unmount 生命周期、动态设置 publicPath/ 路由 base、开启跨域。
  3. 特殊适配：Vue3 + Vite 微应用需使用 vite-plugin-qiankun 插件，解决资源加载和生命周期适配问题。

遵循以上步骤，即可实现 Vue2/Vue3 微应用在 qiankun 架构中的无缝嵌入。

评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包

打赏作者

涔溪

你的鼓励将是我创作的最大动力

¥1 ¥2 ¥4 ¥6 ¥10 ¥20
扫码支付：¥1
获取中
扫码支付

您的余额不足，请更换扫码支付或充值

打赏作者

实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值