首页教程软件教程正文

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

uncle 软件教程 2025年08月6日

0 收藏 0 点赞 773 浏览 4908 个字

摘要 :

文章目录一、微前端架构：基础概念全解析（一）主应用（二）子应用（三）通信机制二、搭建前的准备工作：环境配置很重要（一）创建主应用（二）创建子应用 ……

文
章
目
录

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

（一）主应用
（二）子应用
（三）通信机制

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

（一）创建主应用
（二）创建子应用

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

（一）注册子应用
（二）启动Qiankun
（三）路由配置

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

（一）导出生命周期钩子
（二）配置打包工具（Vite）
（三）添加publicPath适配

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

（一）主应用传递数据
（二）子应用接收数据

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

（一）样式隔离
（二）公共依赖处理
（三）子应用独立路由

七、项目结构参考：清晰的项目布局
八、总结：搭建微前端项目的要点回顾

今天，我就来给大家详细讲讲如何基于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文件负责导出生命周期钩子。