当前位置：首页 > ds >正文

使用 qiankun 实现 Vue3 与 Avalon 混合应用集成实践

ds 2025/8/28 15:27:38

🚀 使用 qiankun 实现 Vue3 与 Avalon 混合应用集成实践

在前端技术演进的过程中，老旧项目的技术栈不可避免地与新技术并存。比如我司的主应用基于多年历史的 avalon.js，但新功能和新页面已经全面采用 Vue3 重构。

为了实现平滑升级、分阶段迁移，同时保证新旧系统互不影响，我们选用了微前端框架 qiankun 来实现 Vue3 与 Avalon 的无缝集成。

本文将详解如何基于 qiankun 集成 Vue3 与 Avalon，支持新旧页面自由切换，并为后续逐步迁移留出扩展空间。

📖 技术栈说明

avalon.js：老牌 MVVM 框架，基于数据双向绑定的前端方案，类似于早期 Vue2。
Vue3：当前主流现代化前端框架，Composition API、响应式系统优化。
qiankun：基于 single-spa 的微前端实现库，支持主应用注册多个子应用，解耦部署、独立运行。

📐 项目架构概览

root/
├── main-app/ # 主应用（avalon项目 + qiankun）
├── sub-vue3/ # 子应用（vue3 项目）
├── sub-xxx/ # 其他未来可能的子应用

🎯 需求目标

保留原有 avalon 页面
新页面统一以 vue3 模块形式开发
支持页面切换新版/旧版
模块解耦，独立开发、独立部署
方便未来逐步迁移至 vue3

🔧 实战步骤

1️⃣ 主应用（avalon + qiankun）

安装 qiankun

npm install qiankun --save

配置 qiankun

// main-app/src/micro-app.js
import { registerMicroApps, start } from 'qiankun';// 注册子应用
registerMicroApps([{name: 'sub-vue3',                    // 子应用名称entry: '//localhost:7100',           // 子应用访问地址container: '#subapp-viewport',       // 子应用挂载容器activeRule: '/vue3'                  // 激活规则}
]);// 启动 qiankun
start();

页面布局（index.html）

<body><div id="avalon-app"><!-- avalon 内容 --></div><div id="subapp-viewport"></div>
</body>

avalon 页面和子应用容器并存。

2️⃣ 子应用（vue3 项目）

配置 vite/vue-cli（以 vite 为例）

// vite.config.js
export default defineConfig({base: '/',server: {port: 7100,cors: true},build: {outDir: 'dist'}
});

子应用 qiankun 适配

// sub-vue3/src/main.js
import { createApp } from 'vue';
import App from './App.vue';let app = null;function render(props = {}) {const { container } = props;app = createApp(App);app.mount(container ? container.querySelector('#app') : '#app');
}// 独立运行时
if (!window.__POWERED_BY_QIANKUN__) {render();
}// qiankun 生命周期钩子
export async function bootstrap() {console.log('vue3 子应用 bootstrap');
}
export async function mount(props) {console.log('vue3 子应用 mount');render(props);
}
export async function unmount() {console.log('vue3 子应用 unmount');if (app) {app.unmount();app = null;}
}

子应用入口 html

<div id="app"></div>

🔄 页面切换实现

我们为主应用提供一个新版/旧版切换按钮：

<button onclick="goToNew()">新版</button>
<button onclick="goToOld()">旧版</button>

function goToNew() {location.hash = '/vue3';
}function goToOld() {location.href = '/#/oldpage';
}

/vue3 路由规则命中 qiankun 激活规则，渲染 Vue3 子应用。其余路由交由 avalon 处理。

⚙️ 兼容 avalon 的注意点

子应用需避免污染全局 window 变量，防止与 avalon 冲突。
子应用 CSS 建议开启 CSS scope 或 CSS modules，避免样式互相覆盖。
子应用和主应用资源路径独立，vite 项目 base 设为 ‘/’，确保子应用路径相对。

📊 未来扩展方案

后续新增子应用直接注册：

registerMicroApps([{ name: 'sub-vue3', entry: '//localhost:7100', container: '#subapp-viewport', activeRule: '/vue3' },{ name: 'sub-admin', entry: '//localhost:7200', container: '#subapp-viewport', activeRule: '/admin' }
]);