Qiankun和Vue3搭建微前端项目的实战步骤详解

今天，我就来给大家详细讲讲如何基于qiankun@2.10和Vue3，一步一步搭建一个微前端项目。这篇文章适合前端开发的新手，也能帮有经验的开发者梳理思路，话不多说，我们直接开始！

一、微前端架构：基础概念全解析

在深入搭建项目之前，咱们得先搞清楚微前端里的几个关键概念。

（一）主应用

主应用就好比是一个项目的“大管家”，负责全局路由的规划、管理整个项目的状态，还要调度各个子应用，控制它们什么时候“登场”，在项目中起着统筹协调的关键作用。

（二）子应用

子应用则是一个个独立开发、独立部署的业务模块。它们就像是一个个“小能手”，各自负责特定的业务功能，而且不同的子应用还能支持不同的技术栈，这就大大提高了项目开发的灵活性。

（三）通信机制

主应用和子应用之间需要进行数据交互，就像人与人之间要交流一样。它们之间主要通过props或者全局状态来共享数据，这样就能协同工作，实现整个项目的功能。

二、搭建前的准备工作：环境配置很重要

（一）创建主应用

我们使用Vite工具来快速搭建主应用的基础框架，它能让我们的开发更高效。在命令行里输入下面这串代码：

# 使用Vite快速创建Vue3项目 npm create vue@latest main-app cd main-app npm install qiankun -S

这段代码的意思是，先用npm create vue@latest命令创建一个名为main-app的Vue3项目，然后进入这个项目目录，再安装qiankun这个库，-S表示把它安装为项目的依赖。

（二）创建子应用

接下来创建子应用，同样使用Vite：

# 创建Vue3子应用 npm create vue@latest micro-vue-app

这样就创建了一个名为micro-vue-app的Vue3子应用。

三、主应用的详细配置：让主应用“运转”起来

（一）注册子应用

在src/micro/apps.ts文件中，我们要定义子应用的相关信息，告诉主应用有哪些子应用，以及它们在哪里。代码如下：

// apps.ts export default [ { name: 'micro-vue-app', entry: '//localhost:7101', // 子应用开发环境地址 container: '#subapp-container', activeRule: '/micro-vue', }, ];

这里定义了一个名为micro-vue-app的子应用，它在开发环境下的地址是//localhost:7101，主应用会把它挂载到#subapp-container这个容器里，当路由匹配到/micro-vue时，就会激活这个子应用。

（二）启动Qiankun

接下来修改main.ts文件，让Qiankun开始工作：

import { createApp } from 'vue'; import { registerMicroApps, start } from 'qiankun'; import App from './App.vue'; import apps from './micro/apps'; const app = createApp(App); // 注册子应用 registerMicroApps(apps); // 启动qiankun start({ prefetch: 'all', // 预加载子应用 sandbox: { experimentalStyleIsolation: true }, // 样式隔离 }); app.mount('#main-app');

这段代码首先引入了必要的模块，然后创建Vue应用实例。接着通过registerMicroApps注册子应用，再用start方法启动Qiankun，这里设置了预加载所有子应用，并且开启了样式隔离，最后把Vue应用挂载到#main-app这个DOM元素上。

（三）路由配置

为了确保主应用的路由不会干扰子应用，我们还要修改router/index.ts文件：

const router = createRouter({ history: createWebHistory(import.meta.env.BASE_URL), routes: [ { path: '/', component: HomeView }, { path: '/micro-vue/*', component: () => import('@/views/MicroContainer.vue') }, ], });

这里配置了两个路由，/路径对应HomeView组件，而/micro-vue/*路径则对应MicroContainer.vue组件，这个路径是用来匹配子应用的路由的。

四、子应用改造：让子应用适应微前端架构

（一）导出生命周期钩子

在子应用的入口文件src/main.ts中，我们要导出一些生命周期钩子，让主应用能够控制子应用的启动、挂载和卸载。代码如下：

import { createApp } from 'vue'; import App from './App.vue'; let instance: any = null; function render(props: any) { const { container } = props; instance = createApp(App); instance.mount(container?.querySelector('#app') || '#app'); } // 独立运行时直接渲染 if (!window.__POWERED_BY_QIANKUN__) { render({}); } // 导出Qiankun生命周期 export async function bootstrap() { console.log('Vue子应用启动'); } export async function mount(props: any) { render(props); } export async function unmount() { instance.unmount(); instance = null; }

这里定义了一个render函数来渲染Vue应用，并且根据window.__POWERED_BY_QIANKUN__这个变量判断是否在微前端环境中。如果不是，就直接渲染。然后导出了bootstrap、mount和unmount这三个生命周期函数，分别用于子应用的启动、挂载和卸载。

（二）配置打包工具（Vite）

修改vite.config.ts文件，让子应用能够正确地打包和部署：

export default defineConfig({ base: '/micro-vue', // 与主应用activeRule匹配 server: { port: 7101, cors: true, }, build: { rollupOptions: { output: { format: 'system', // 使用SystemJS格式 }, }, }, });

这里设置了base为/micro-vue，要和主应用中配置的activeRule相匹配。还指定了开发服务器的端口为7101，允许跨域请求，并且设置打包输出格式为system，使用SystemJS来加载模块。

（三）添加publicPath适配

在子应用的根目录下创建public-path.js文件，用于适配不同的部署环境：

if (window.__POWERED_BY_QIANKUN__) { __webpack_public_path__ = window.__INJECTED_PUBLIC_PATH_BY_QIANKUN__; }

这段代码的作用是，当在微前端环境中时，动态地修改__webpack_public_path__，确保子应用的资源能够正确加载。

五、主应用与子应用通信：实现数据交互

（一）主应用传递数据

主应用可以在注册子应用的时候，通过props给子应用传递数据，就像这样：

// 注册子应用时添加props registerMicroApps(apps, { beforeLoad: (app) => { return { ...app, props: { globalToken: '主应用传递的Token' }, }; }, });

这里在注册子应用时，给每个子应用添加了一个props对象，里面包含了一个globalToken属性，值为“主应用传递的Token”。

（二）子应用接收数据

子应用在mount生命周期中可以获取主应用传递过来的数据：

export async function mount(props: any) { console.log('接收主应用数据:', props.globalToken); render(props); }

在子应用的mount函数里，通过props.globalToken就可以获取到主应用传递的数据，并打印出来。

六、项目优化与常见问题解决：让项目更完善

（一）样式隔离

在微前端项目中，样式隔离很重要，不然子应用的样式可能会互相影响。有两种常见的解决方案：

方案一：在启动Qiankun时，开启sandbox: { experimentalStyleIsolation: true }，它会给子应用的样式添加前缀，避免样式冲突。
方案二：使用CSS Modules或Shadow DOM，这两种方式也能有效地实现样式隔离，让各个子应用的样式互不干扰。

（二）公共依赖处理

为了避免多个子应用重复引入相同的依赖，浪费资源，可以通过webpack的externals或者Vite的build.rollupOptions.external来共享公共库，比如Vue3。这样，在打包时就不会把这些公共库重复打包到每个子应用中，提高了项目的性能。

（三）子应用独立路由

子应用需要有自己独立的路由，并且要根据是否在微前端环境中进行配置。可以使用createWebHistory并设置base：

const router = createRouter({ history: createWebHistory(window.__POWERED_BY_QIANKUN__? '/micro-vue' : '/'), });

这里根据window.__POWERED_BY_QIANKUN__的值来判断是否在微前端环境中，如果是，就把base设置为/micro-vue，否则设置为/。

七、项目结构参考：清晰的项目布局

了解项目的整体结构，有助于我们更好地理解和维护项目：

├── main-app/ # 主应用 │ ├── src/ │ │ ├── micro/ # 微前端配置 │ │ └── views/MicroContainer.vue ├── micro-vue-app/ # Vue3子应用 │ ├── src/ │ │ └── main.ts # 导出生命周期

主应用的src/micro目录存放微前端相关的配置，views/MicroContainer.vue用于承载子应用。子应用的src/main.ts文件负责导出生命周期钩子。