微前端入门：qiankun + Vue 3 + Vite 从0搭建第一个微前端应用

CodeAI2026-04-16 10:04

前言

随着业务规模不断扩大，前端应用体积越来越大，单一巨石应用的开发维护成本越来越高：

  • 多人协作开发，代码冲突频繁
  • 整体编译打包时间越来越长
  • 技术栈陈旧，无法引入新技术
  • 发布一个小改动需要整个应用重新上线

微前端架构应运而生，通过将巨石应用拆分为多个独立可交付的微应用，实现团队自治、独立开发、独立部署，从架构层面解决这些问题。

目前社区中比较成熟的微前端方案里，qiankun 是蚂蚁集团开源的企业级方案，经过大量业务验证，生态成熟，api 友好，是落地微前端最稳妥的选择。

本文带你一步步从 0 搭建第一个 qiankun 微前端应用，基于最新的 Vue 3 + Vite 技术栈，解决了网上大部分教程配置错误的问题。读完本文你就能跑通一个可工作的微前端应用。

技术选型

层级 选型 理由
微前端框架 qiankun 成熟稳定，社区案例多，坑少
前端框架 Vue 3 主流稳定，性能优秀，生态完善
构建工具 Vite 开发启动快，热更新体验好，是当前主流趋势
路由 Vue Router 4 官方标准，配合 qiankun 路由联动方案成熟

整体架构

graph TD A[主应用/MainApp] --> B[微应用1/App1] A --> C[微应用2/App2] style A fill:#f9f,stroke:#333,stroke-width:2px style B fill:#bbf,stroke:#333,stroke-width:1px style C fill:#bbf,stroke:#333,stroke-width:1px
  • 主应用（基座）： 负责微应用注册与生命周期管理、全局导航布局、公共依赖加载。
  • 微应用： 各个业务模块独立开发、独立运行、独立部署。
  • 最终效果：用户在浏览器中切换不同业务模块，感觉就像在同一个应用里，实际上每个模块都是独立的。

项目初始化

我们需要创建三个项目：一个主应用，两个微应用。

bash 复制代码 
# 创建主应用
npm create vite@latest main-app -- --template vue

# 创建微应用一
npm create vite@latest micro-app-vue1 -- --template vue

# 创建微应用二
npm create vite@latest micro-app-vue2 -- --template vue

最终目录结构：

bash 复制代码 
micro-front/
├── main-app/          # 主应用（基座）
├── micro-app-vue1/    # 微应用1
├── micro-app-vue2/    # 微应用2
└── README.md

本文档对应的完整代码已经开源在 github.com/wenbiyou/mi...，你可以直接克隆运行。

第一步：主应用配置 qiankun

安装依赖

bash 复制代码 
cd main-app
npm install qiankun vue-router@4

qiankun 注册与启动

修改 src/main.js：

javascript 复制代码 
import { createApp } from 'vue'
import { createRouter, createWebHistory } from 'vue-router'
import { registerMicroApps, start } from 'qiankun'
import App from './App.vue'

const app = createApp(App)
const router = createRouter({
  history: createWebHistory('/'),
  routes: [
    { path: '/', redirect: '/app1' },
    { path: '/:pathMatch(.*)*', component: () => import('./views/NotFound.vue') }
  ]
})

app.use(router)
app.mount('#app')

// 微应用配置
const microApps = [
  {
    name: 'micro-app-vue1',
    entry: '//localhost:7100', // 开发环境入口
    activeRule: '/app1', // 激活规则：路径以 /app1 开头时激活
    container: '#micro-container' // 挂载容器
  },
  {
    name: 'micro-app-vue2',
    entry: '//localhost:7101',
    activeRule: '/app2',
    container: '#micro-container'
  }
]

// 注册微应用
registerMicroApps(microApps, {
  beforeLoad: [app => console.log('before load', app.name)],
  beforeMount: [app => console.log('before mount', app.name)],
  afterMount: [app => console.log('after mount', app.name)],
  afterUnmount: [app => console.log('after unmount', app.name)]
})

// 启动 qiankun
start({
  sandbox: {
    strictStyleIsolation: false,
    experimentalStyleIsolation: true // 开启实验性样式隔离，兼容性更佳
  },
  prefetch: 'all' // 预加载微应用静态资源
})

添加主应用布局

修改 src/App.vue：

vue 复制代码 
<template>
  <div id="main-app">
    <header class="main-header">
      <div class="logo">
        <h1>微前端主应用</h1>
      </div>
      <nav class="nav">
        <router-link to="/app1">应用一</router-link>
        <router-link to="/app2">应用二</router-link>
      </nav>
    </header>
    <!-- qiankun 挂载容器 -->
    <div id="micro-container" class="micro-container"></div>
  </div>
</template>

<style scoped>
.main-header {
  display: flex;
  justify-content: space-between;
  align-items: center;
  padding: 0 20px;
  background: #2c3e50;
  color: white;
}
.nav {
  display: flex;
  gap: 20px;
}
.nav a {
  color: white;
  text-decoration: none;
}
.nav a.router-link-exact-active {
  color: #42b983;
  font-weight: bold;
}
.micro-container {
  padding: 20px;
}
</style>

Vite 配置

修改 vite.config.js：

javascript 复制代码 
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [vue()],
  server: {
    port: 7099, // 主应用端口，避免和微应用冲突
    cors: true // 开启跨域，允许加载微应用资源
  }
})

主应用配置完成！接下来配置微应用。

第二步：微应用适配 qiankun

以 micro-app-vue1 为例，micro-app-vue2 只需要修改端口和名称即可。

安装依赖

bash 复制代码 
cd micro-app-vue1
npm install vite-plugin-qiankun

修改入口文件适配生命周期

修改 src/main.js：

javascript 复制代码 
import { createApp } from 'vue'
import { createRouter, createWebHistory } from 'vue-router'
import { renderWithQiankun, qiankunWindow } from 'vite-plugin-qiankun/es/helper'
import App from './App.vue'
import './style.css'

let app = null

function render(props = {}) {
  const { container } = props
  const mountNode = container ? container.querySelector('#app') : '#app'

  // 每次渲染新建 router，避免状态污染
  const router = createRouter({
    history: createWebHistory(qiankunWindow.__POWERED_BY_QIANKUN__ ? '/app1' : '/'),
    routes: [
      { path: '/', component: () => import('./views/Home.vue') },
      { path: '/about', component: () => import('./views/About.vue') }
    ]
  })

  app = createApp(App)
  app.use(router)
  app.mount(mountNode)
}

// 使用 renderWithQiankun 包裹生命周期
renderWithQiankun({
  bootstrap() {
    console.log('[micro-app-vue1] bootstrap')
  },
  mount(props) {
    console.log('[micro-app-vue1] mount', props)
    render(props)
  },
  unmount() {
    console.log('[micro-app-vue1] unmount')
    app?.unmount()
    app = null
  }
})

// 独立运行
if (!qiankunWindow.__POWERED_BY_QIANKUN__) {
  render()
}

关键 Vite 配置

修改 vite.config.js：

javascript 复制代码 
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import qiankun from 'vite-plugin-qiankun'

export default defineConfig({
  base: '/app1/', //  开发环境基路径，生产环境请根据部署路径动态设置
  plugins: [
    vue(),
    qiankun('micro-app-vue1', {
      useDevMode: true // 开发模式必须开启
    })
  ],
  server: {
    port: 7100, // 微应用端口
    cors: true, // 必须开启跨域，主应用才能访问
    headers: {
      'Access-Control-Allow-Origin': '*'
    },
    origin: 'http://localhost:7100' // 必须配置完整的 origin，qiankun 才能正确获取资源
  },
  build: {
    // 生产构建必须配置 UMD 格式供 qiankun 加载
    lib: {
      entry: './src/main.js',
      name: 'micro-app-vue1',
      formats: ['umd'],
      fileName: () => 'index.js'
    }
  }
})

关键提示： 这是网上大多数教程配置错误的地方！

  1. server.origin 必须是完整 URL，否则 qiankun 无法正确加载微应用资源
  2. base 必须和 activeRule 保持一致
  3. 生产构建必须配置 build.lib 输出 UMD 格式

第二个微应用 micro-app-vue2 配置类似，只需要修改：

  • 端口改为 7101
  • base 改为 /app2/
  • name 改为 micro-app-vue2

本地运行验证

我们需要三个终端分别启动：

bash 复制代码 
# 终端一：主应用
cd main-app && npm install && npm run dev
# 访问 http://localhost:7099

# 终端二：微应用一
cd micro-app-vue1 && npm install && npm run dev
# 监听 http://localhost:7100

# 终端三：微应用二
cd micro-app-vue2 && npm install && npm run dev
# 监听 http://localhost:7101

打开浏览器访问 http://localhost:7099，你应该能看到：

  1. 主应用头部导航显示
  2. 微应用一正常加载3.点击导航切换到微应用二，微应用二正常加载
  3. 切换回微应用一，微应用一再次正常加载

如果看到这个效果，恭喜你！你的第一个 qiankun 微前端应用已经跑通了！

FAQ

Q: 按照步骤配置后，微应用还是加载不出来，怎么办？

A: 先检查这几点：

  1. micro-app-vue1 的 vite.config.js 中 server.origin 是否配置了完整 URL (http://localhost:7100)
  2. 端口是否被占用，三个服务都正常启动了吗？
  3. 浏览器控制台有没有报错？常见报错我们在第三篇文章会详细讲解。

Q: 微应用可以独立运行吗？

A: 可以！直接访问 http://localhost:7100 就能独立运行微应用一，这是最佳实践------每个微应用必须能够独立运行，方便开发调试。

Q: 为什么每次 mount 都要重新创建路由？

A: 为了避免状态污染。如果路由只创建一次重复使用，上次的状态会残留到下次挂载，重新创建可以保证每次挂载都是干净的状态。

Q: 生产环境部署和开发环境有什么不同？

A: 打包优化、部署方案、常见坑点我们放在第三篇文章详细讲解。第二篇我们先把核心概念讲清楚。

本章小结

你已经完成了：

  1. 创建了主应用和两个微应用的项目结构
  2. 主应用注册并启动了 qiankun
  3. 微应用适配了 qiankun 生命周期
  4. 配置了正确的 Vite 配置（解决了大多数教程的错误）
  5. 本地运行验证可以正常切换

下一篇我们深入讲解 qiankun 核心概念：路由联动、样式隔离、跨应用通信。

相关推荐
eastyuxiao2 小时前
多机 OpenClaw 互联完整方案
人工智能·架构
AI2512242 小时前
AI文生视频技术解析：主流工具的模型架构与能力对比
人工智能·架构·音视频
SuperEugene3 小时前
Vue3 配置驱动表格：列配置/操作配置/分页配置，统一表格渲染｜配置驱动开发实战篇
前端·javascript·vue.js·驱动开发·架构
ZHENGZJM3 小时前
Server-Sent Events (SSE) 接口实现
架构·go·gin
人道领域3 小时前
GPT-5架构泄露？Kubernetes 1.31发布与Rust重构浪潮下的云原生之变
gpt·云原生·架构
人道领域4 小时前
【黑马点评日记02】Redis解决Tomcat集群Session共享问题
java·前端·后端·架构·tomcat·firefox
cheems95274 小时前
[JavaEE]深度解构 Spring 核心：从控制反转 (IoC) 到依赖注入 (DI) 的架构演进
java·spring·架构·java-ee
立莹Sir4 小时前
【架构图解+实战配置】SaaS多租户资源隔离的云原生完整方案
云原生·架构
LONGZETECH4 小时前
破解智能网联汽车教学痛点！龙泽科技AR仿真软件，重新定义实训新范式
科技·架构·汽车·ar·职业教育·汽车仿真教学软件·汽车故障诊断
热门推荐
012026年4月技术前沿：AI大模型爆发、智能体革命与量子安全新纪元02GitHub 镜像站点03一周AI热点速览（2026.03.31-04.06）：GPT-6曝光、谷歌开源Gemma 4、资本狂飙与模型军备竞赛04GPT-6核心能力解析及与现有主流大模型对比05基于 Docker 部署 Hermes Agent 并接入飞书机器人的完整指南06GPT-6发布日深度解析-Symphony架构200万Token实战07零成本！Ollama本地部署国产大模型全指南（支持Kimi-K2.5/GLM-5/Qwen，新手秒上手）08AI Weekly | 2026年4月第二周 · GitHub热门项目与AI发展趋势深度解析09从限购到畅通：GLM-5.1 Coding Plan接入攻略10CodeBuddy与WorkBuddy深度对比：腾讯两款AI工具差异及实操指南