企业官网建设流程全解析

Vue2老项目救星：用Qiankun微前端低成本接入Vue3子模块（附完整配置流程）

当你的团队还在为Vue2历史项目的技术栈升级发愁时，微前端架构正在成为解决这一痛点的银弹方案。不同于全盘重构的高风险和高成本，通过Qiankun这类微前端框架，我们可以实现Vue2主应用与Vue3子应用的渐进式融合。这种方式特别适合那些业务复杂、模块众多且开发团队庞大的项目，既能保留原有投资，又能逐步引入新技术栈的优势。

1. 为什么选择Qiankun进行渐进式升级

在技术选型过程中，我们评估了多种微前端方案，最终Qiankun凭借以下核心优势脱颖而出：

• 技术栈无关性：主应用和子应用可以使用完全不同的技术栈，Vue2和Vue3可以和谐共存
• 独立开发部署：每个子应用都有自己的代码仓库和CI/CD流程，不会影响主应用
• 样式隔离机制：通过Shadow DOM和scoped CSS实现样式隔离，避免全局污染
• 运行时沙箱：JavaScript执行环境隔离，防止全局变量冲突
• 通信机制完善：提供props和全局状态管理两种通信方式

实际项目中我们发现，Qiankun对Vue2/Vue3混合使用的支持度最好，社区活跃度也最高，遇到问题更容易找到解决方案。

2. 基础环境搭建与配置

2.1 主应用(Vue2)初始化

首先确保主应用是基于Vue CLI创建的Vue2项目：

# 创建Vue2主应用 vue create main-app cd main-app

安装Qiankun核心库：

npm install qiankun -S

2.2 子应用(Vue3)初始化

使用Vite创建Vue3子应用：

# 创建Vue3子应用 npm create vite@latest sub-app --template vue cd sub-app npm install

子应用需要额外安装qiankun适配器：

npm install vite-plugin-qiankun -D

3. 主应用关键配置详解

3.1 微应用注册机制

在主应用src目录下创建micro-apps.js：

const microApps = [ { name: 'vue3-app', entry: '//localhost:3000', // Vue3子应用开发服务器地址 activeRule: '/vue3', props: { routerBase: '/vue3' // 传递给子应用的基础路由 } } ] export default microApps

3.2 主应用启动配置

修改main.js文件：

import { registerMicroApps, start } from 'qiankun' import microApps from './micro-apps' registerMicroApps(microApps, { beforeLoad: app => { console.log('before load', app.name) }, beforeMount: [app => { console.log('before mount', app.name) }], afterMount: [app => { console.log('after mount', app.name) }], afterUnmount: [app => { console.log('after unmount', app.name) }] }) // 启动qiankun start({ sandbox: { experimentalStyleIsolation: true // 开启样式隔离 } }) // 原有Vue2应用启动逻辑 new Vue({ router, store, render: h => h(App) }).$mount('#app')

3.3 路由配置要点

主应用路由需要使用history模式，并添加通配路由：

const routes = [ // ...其他路由 { path: '/vue3/*', name: 'vue3-container', component: () => import('@/views/MicroContainer.vue') } ]

创建MicroContainer.vue作为子应用容器：

<template> <div id="vue3-container"></div> </template> <script> export default { name: 'MicroContainer' } </script> <style scoped> #vue3-container { width: 100%; height: 100%; } </style>

4. Vue3子应用适配改造

4.1 Vite配置调整

修改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-app', { // 与主应用注册的name一致 useDevMode: true }) ], server: { port: 3000, cors: true, headers: { 'Access-Control-Allow-Origin': '*' } }, base: '/vue3/', // 与activeRule一致 build: { lib: { entry: 'src/main.js', name: 'vue3-app', formats: ['umd'] } } })

4.2 生命周期适配

改造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) app.mount(container ? container.querySelector('#app') : '#app') } // 独立运行 if (!qiankunWindow.__POWERED_BY_QIANKUN__) { render() } // qiankun生命周期 renderWithQiankun({ bootstrap() { console.log('vue3-app bootstrap') }, mount(props) { console.log('vue3-app mount', props) render(props) }, unmount() { console.log('vue3-app unmount') app.unmount() app = null } })

4.3 路由适配处理

子应用路由需要根据运行环境动态设置base：

import { createRouter, createWebHistory } from 'vue-router' import { qiankunWindow } from 'vite-plugin-qiankun/dist/helper' const router = createRouter({ history: createWebHistory( qiankunWindow.__POWERED_BY_QIANKUN__ ? '/vue3/' : '/' ), routes: [ // 子应用路由配置 ] }) export default router

5. 高级功能与问题排查

5.1 应用间通信方案

Qiankun提供了两种通信方式：

1. 基于props的通信：

   • 主应用通过props传递数据
   • 子应用通过props接收并使用

2. 全局状态管理：

   • 使用initGlobalState API创建全局状态
   • 主应用和子应用都可以订阅和修改状态

// 主应用中初始化全局状态 import { initGlobalState } from 'qiankun' const actions = initGlobalState({ user: null, token: '' }) // 子应用中获取全局状态 export function mount(props) { props.onGlobalStateChange((state, prev) => { console.log('状态变更:', state, prev) }) props.setGlobalState({ user: { name: 'admin' } }) }

5.2 常见问题解决方案

5.3 性能优化建议

• 预加载策略：在浏览器空闲时预加载子应用资源
• 依赖共享：通过webpack externals共享公共库
• 按需加载：非核心子应用延迟加载
• 缓存策略：合理配置子应用资源的缓存头

// 主应用中配置预加载 import { prefetchApps } from 'qiankun' prefetchApps([ { name: 'vue3-app', entry: '//localhost:3000' } ])

在实际项目落地过程中，我们建议先在一个非核心模块试点，验证技术方案可行性后再逐步推广。同时要建立完善的监控体系，及时发现和解决微前端架构带来的新挑战。