使用 Qiankun 微前端框架搭建 Vue3 项目实践指南

前言

在大型前端项目中，微前端架构能有效解决多团队协作、技术栈异构和独立部署等问题。本文基于 qiankun@2.10 和 Vue3，分享如何从零搭建一个微前端项目。

---

一、微前端核心概念

• 主应用（Base App）：负责全局路由、状态管理和子应用调度。

• 子应用（Micro App）：独立开发、部署的业务模块，支持不同技术栈。

• 通信机制：主应用与子应用间通过 props 或全局状态共享数据。

---

二、环境准备

1. 创建主应用

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

2. 创建子应用

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

---

三、主应用配置

1. 注册子应用

在 src/micro/apps.ts 中定义子应用信息：

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

2. 启动 Qiankun

修改 main.ts：

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');

3. 路由配置

修改 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') },
  ],
});

---

四、子应用改造

1. 导出生命周期钩子

在子应用入口文件 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;
}

2. 配置打包工具（Vite）

修改 vite.config.ts：

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

3. 添加 publicPath 适配

在子应用根目录创建 public-path.js：

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

---

五、主应用与子应用通信

1. 主应用传递数据

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

2. 子应用接收数据

在子应用 mount 生命周期中获取：

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

---

六、常见问题与优化

1. 样式隔离

• 方案一：开启 sandbox: { experimentalStyleIsolation: true }（添加样式前缀）

• 方案二：使用 CSS Modules 或 Shadow DOM

2. 公共依赖处理

通过 webpack 的 externals 或 Vite 的 build.rollupOptions.external 共享公共库（如 Vue3）。

3. 子应用独立路由

子应用需使用 createWebHistory 并配置 base：

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

---

七、项目结构参考

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

---

总结

通过 Qiankun 实现微前端架构，可以显著提升大型项目的可维护性和扩展性。重点注意：

1. 主应用与子应用的生命周期管理

2. 路由和样式的隔离方案

3. 高效的通信机制

示例代码仓库：GitHub链接

欢迎在评论区交流实践中遇到的问题！

---

希望这篇指南能帮助你快速上手 Qiankun 微前端开发！ 🚀