登录
微前端入门：qiankun + Vue 3 + Vite 从0搭建第一个微前端应用
2026年4月16日 07:28
前言
随着业务规模不断扩大，前端应用体积越来越大，单一巨石应用的开发维护成本越来越高：
- 多人协作开发，代码冲突频繁
- 整体编译打包时间越来越长
- 技术栈陈旧，无法引入新技术
- 发布一个小改动需要整个应用重新上线
微前端架构应运而生，通过将巨石应用拆分为多个独立可交付的微应用，实现团队自治、独立开发、独立部署，从架构层面解决这些问题。
目前社区中比较成熟的微前端方案里，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
- 主应用（基座）： 负责微应用注册与生命周期管理、全局导航布局、公共依赖加载。
- 微应用： 各个业务模块独立开发、独立运行、独立部署。
- 最终效果：用户在浏览器中切换不同业务模块，感觉就像在同一个应用里，实际上每个模块都是独立的。
项目初始化
我们需要创建三个项目：一个主应用，两个微应用。
# 创建主应用
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
最终目录结构：
micro-front/
├── main-app/ # 主应用（基座）
├── micro-app-vue1/ # 微应用1
├── micro-app-vue2/ # 微应用2
└── README.md
本文档对应的完整代码已经开源在 github.com/wenbiyou/mi…，你可以直接克隆运行。
第一步：主应用配置 qiankun
安装依赖
cd main-app
npm install qiankun vue-router@4
qiankun 注册与启动
修改 src/main.js：
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：
<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：
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 只需要修改端口和名称即可。
安装依赖
cd micro-app-vue1
npm install vite-plugin-qiankun
修改入口文件适配生命周期
修改 src/main.js：
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：
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'
}
}
})
关键提示： 这是网上大多数教程配置错误的地方！
server.origin必须是完整 URL，否则 qiankun 无法正确加载微应用资源base必须和activeRule保持一致- 生产构建必须配置
build.lib输出 UMD 格式
第二个微应用 micro-app-vue2 配置类似，只需要修改：
- 端口改为
7101 -
base改为/app2/ - name 改为
micro-app-vue2
本地运行验证
我们需要三个终端分别启动：
# 终端一：主应用
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，你应该能看到：
- 主应用头部导航显示
- 微应用一正常加载3.点击导航切换到微应用二，微应用二正常加载
- 切换回微应用一，微应用一再次正常加载
如果看到这个效果，恭喜你！你的第一个 qiankun 微前端应用已经跑通了！
FAQ
Q: 按照步骤配置后，微应用还是加载不出来，怎么办？
A: 先检查这几点：
-
micro-app-vue1的vite.config.js中server.origin是否配置了完整 URL (http://localhost:7100) - 端口是否被占用，三个服务都正常启动了吗？
- 浏览器控制台有没有报错？常见报错我们在第三篇文章会详细讲解。
Q: 微应用可以独立运行吗？
A: 可以！直接访问 http://localhost:7100 就能独立运行微应用一，这是最佳实践——每个微应用必须能够独立运行，方便开发调试。
Q: 为什么每次 mount 都要重新创建路由？
A: 为了避免状态污染。如果路由只创建一次重复使用，上次的状态会残留到下次挂载，重新创建可以保证每次挂载都是干净的状态。
Q: 生产环境部署和开发环境有什么不同？
A: 打包优化、部署方案、常见坑点我们放在第三篇文章详细讲解。第二篇我们先把核心概念讲清楚。
本章小结
你已经完成了：
- 创建了主应用和两个微应用的项目结构
- 主应用注册并启动了 qiankun
- 微应用适配了 qiankun 生命周期
- 配置了正确的 Vite 配置（解决了大多数教程的错误）
- 本地运行验证可以正常切换
下一篇我们深入讲解 qiankun 核心概念：路由联动、样式隔离、跨应用通信。
