基于 qiankun + vite + vue3 构建微前端应用实践

核心内容摘要​​

1. ​​技术栈组合​​
   • 采用 Vite + Vue3 + Qiankun 构建微前端架构
   • 主应用和子应用独立开发部署，通过 Qiankun 集成
     ​​2. 主应用关键配置​​
   • 通过 registerMicroApps 注册子应用，配置路由匹配规则（activeRule）
   • 使用 start() 启动微前端框架
   • 动态容器设计：子应用挂载到主应用的 #sub-container 节点
     ​​3. 子应用特殊处理​​
   • 使用 vite-plugin-qiankun 插件简化集成
   • 动态路由适配：根据是否在 Qiankun 环境切换路由基础路径
   • 生命周期管理：通过 renderWithQiankun 暴露挂载/卸载钩子
   • 必须配置 UMD 格式打包和跨域支持
2. ​​开发环境优化​​
   • 主应用代理子应用请求（解决端口问题）
   • 子应用需配置 base 路径和 CORS 头
3. ​​生产环境要求​​
   • 静态资源部署到独立路径（如 /sub-app/）
   • Nginx 需配置路径重写规则
   • 推荐预加载和依赖共享优化性能

介绍

Qiankun

qiankun 是一个基于 single-spa 的微前端实现库，旨在帮助大家能更简单、无痛的构建一个生产可用微前端架构系统。

微前端

微前端是一种多个团队通过独立发布功能的方式来共同构建现代化 web 应用的技术手段及方法策略。

微前端架构具备以下几个核心价值：

• 技术栈无关

  主框架不限制接入应用的技术栈，微应用具备完全自主权

• 独立开发、独立部署

  微应用仓库独立，前后端可独立开发，部署完成后主框架自动完成同步更新

• 增量升级

  在面对各种复杂场景时，我们通常很难对一个已经存在的系统做全量的技术栈升级或重构，而微前端是一种非常好的实施渐进式重构的手段和策略

• 独立运行时

  每个微应用之间状态隔离，运行时状态不共享

Code

基于 vite + vue3 + qiankun 构建一个微前端应用；创建一个文件夹 my-apps;

依赖版本：

• node: >= 18
• vue: 3.5.16
• vite: 6.3.5
• qiankun: 2.10.16
• vue-router: 4.5.1

主应用

在 my-apps 下执行如下命令：

$ pnpm create vue   # 设置项目名称为 main-app
$ cd main-app
$ pnpm i

为 main-app 安装相关依赖：

$ pnpm i qiankun

App.vue

<template><router-view></router-view>
</template>

router.js

要为子应用设置对应的匹配路径

import { createRouter, createWebHistory } from "vue-router";const routes = [{ path: "/", name: "home", component: () => import("../views/Home.vue") },{ path: "/sub-app/:pathMatch(.*)*", name: "sub-app", component: () => import("../views/SubApp.vue") },
];const router = createRouter({history: createWebHistory(),routes,
});export default router;

main.js

注册子应用

import { createApp } from "vue";
import App from "./App.vue";
import { registerMicroApps, start, loadMicroApp } from "qiankun";
import router from "./router/index.js";const app = createApp(App);app.use(router);registerMicroApps([{name: "sub-app",entry: "//localhost:7100",container: "#sub-container",activeRule: "/sub-app",props: {author: "Mino",},},]
);
// 可以设置相关生命周期函数，beforeMount、beforeLoad、afterMount 等start();app.mount("#app");

views/Home.vue

<template><div>Home</div><router-link to="/sub-app">sub app</router-link>
</template>

views/SubApp.vue

<template><div>this is a sub app:</div><br><div id="sub-container" style="border: 1px solid thistle; height: 600px;"></div>
</template>

子应用

在 my-apps 下执行如下命令：

$ pnpm create vue   # 设置项目名称为 sub-app
$ cd sub-app
$ pnpm i

为 sub-app 安装相关依赖：

$ pnpm i vite-plugin-qiankun -D

App.vue

<template><router-view></router-view>
</template>

router.js

import { createRouter, createWebHistory, createMemoryHistory } from "vue-router";const router = createRouter({history: createWebHistory("/sub-app"),routes: [{path: "/",name: "Home",component: () => import("../views/Home.vue"),},{path: "/about",name: "About",component: () => import("../views/About.vue"),},],
});export default router;

main.js

• 使用 qiankunWindow 判断是否是独立运行
• 在 window 上挂载子应用的钩子函数

import { createApp } from "vue";
import App from "./App.vue";
import router from "./router/index.js";
import { renderWithQiankun, qiankunWindow } from "vite-plugin-qiankun/dist/helper";let instance = null;function render(props = {}) {const { container } = props;instance = createApp(App);instance.use(router);instance.mount(container || "#app");
}// 独立运行时直接渲染
if (!qiankunWindow.__POWERED_BY_QIANKUN__) { // window.proxyrender();
} else {renderWithQiankun({ // window.moudleQiankunAppLifeCyclesmount(props) {render(props);},bootstrap() {},update(props) {},unmount() {instance?.unmount();},});
}

vite.config.js

需要为子应用配置 base、server、build；
根据具体情况，在打包时，需要修改 base 路径；

import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import qiankun from "vite-plugin-qiankun";export default defineConfig({plugins: [vue(),qiankun("sub-app", {useDevMode: true, // 开发模式}),],base: import.meta.env.DEV ? "/sub-app/" : "[prod sub app url]",server: {port: 7100,cors: true,origin: "http://localhost:7100",},build: {rollupOptions: {output: {format: "umd",},},},
});

views/Home.vue

<template><div>sub app home</div><br><router-link to="/about">sub app about</router-link>
</template>

运行

分别运行主应用和子应用，并访问主应用地址；

访问主应用首页路径：/

访问子应用的首页路径：/sub-app

访问子应用的 about 路径：/sub-app/about

完整代码 git