qiankun 微前端应用入门教程：从搭建到部署

微前端就是把一个大前端项目拆成好几个独立的小应用来开发，qiankun 是阿里搞的微前端框架，不管你子应用是 Vue、React 还是 Angular，都能无缝接进去。这篇教程带你从 0 搞出一个能跑的 qiankun 微前端项目，下面跟着步骤来就行~

一、先搞懂这几个概念

开始之前，得知道 qiankun 里这几个角色是干嘛的：

主应用（基座）：相当于"容器"，负责加载、切换各个子应用，还能提供一些公共的东西（比如全局路由、状态）；
子应用：可以单独开发、单独部署的小应用，既能嵌在主应用里用，也能自己跑起来；
生命周期钩子：子应用被主应用加载/卸载时会触发的函数（比如启动、挂载、卸载这几个环节）。

二、准备环境

本地得装这俩：

Node.js（v14 以上就行）
包管理工具（npm、yarn、pnpm 随便选一个）

三、第一步：搭个主应用（用 Vue 举例子）

先搞个 Vue 主应用当"容器"。

3.1 初始化主应用

打开终端敲命令：

bash 复制代码

# 创建 Vue 主应用
vue create qiankun-main
cd qiankun-main
# 装 qiankun
npm i qiankun -S

3.2 配置主应用

打开 main.js，把 qiankun 配置上，注册子应用：

javascript 复制代码

import { createApp } from 'vue';
import { registerMicroApps, start } from 'qiankun';
import App from './App.vue';
import router from './router';

const app = createApp(App);
app.use(router);
app.mount('#app');

// 1. 注册子应用：告诉主应用要加载哪些子应用
registerMicroApps([
  {
    name: 'vue-subapp', // 子应用名字，得唯一
    entry: '//localhost:8081', // 子应用的地址（开发时用本地端口）
    container: '#subapp-container', // 子应用要挂在主应用的哪个 DOM 里
    activeRule: '/vue-subapp', // 访问哪个路由时加载这个子应用
  },
]);

// 2. 启动 qiankun
start();

3.3 给主应用加个页面布局

改 App.vue，加个导航栏和子应用的挂载区域：

vue 复制代码

<template>
  <div class="main-app">
    <nav class="nav-bar">
      <router-link to="/">主应用首页</router-link>
      <router-link to="/vue-subapp">Vue 子应用</router-link>
    </nav>
    <!-- 子应用就挂在这个盒子里 -->
    <div id="subapp-container" class="subapp-box"></div>
  </div>
</template>

<style>
.main-app {
  padding: 20px;
}
.nav-bar a {
  margin-right: 20px;
  text-decoration: none;
  color: #333;
}
.nav-bar a:hover {
  color: #42b983;
}
.subapp-box {
  margin-top: 20px;
  padding: 20px;
  border: 1px solid #eee;
}
</style>

四、第二步：搞个子应用（还是用 Vue 举例）

子应用不能直接用，得改改配置，让 qiankun 能识别它。

4.1 初始化子应用

终端继续敲：

bash 复制代码

vue create qiankun-vue-subapp
cd qiankun-vue-subapp

4.2 子应用适配改造

4.2.1 改 `main.js`，暴露生命周期函数

qiankun 需要子应用提供启动、挂载、卸载这几个钩子，所以得把 main.js 改成这样：

javascript 复制代码

import { createApp } from 'vue';
import App from './App.vue';
import router from './router';

let appInstance = null;

// 渲染子应用的函数
function render(props = {}) {
  const { container } = props;
  // 要么挂在主应用给的容器里，要么挂在自己的 #app 上（单独运行时）
  appInstance = createApp(App);
  appInstance.use(router);
  appInstance.mount(container ? container.querySelector('#app') : '#app');
}

// 如果是单独运行（没被 qiankun 加载），直接渲染
if (!window.__POWERED_BY_QIANKUN__) {
  render();
}

// 暴露给 qiankun 的生命周期钩子
export async function bootstrap() {
  console.log('Vue 子应用：我准备启动啦~');
}

export async function mount(props) {
  console.log('Vue 子应用：我被主应用挂载啦！', props);
  render(props);
}

export async function unmount() {
  console.log('Vue 子应用：我被主应用卸载啦~');
  appInstance.unmount();
  appInstance = null;
}

4.2.2 加个 `vue.config.js` 配置

子应用得解决跨域和资源冲突的问题，所以新建 vue.config.js：

javascript 复制代码

module.exports = {
  devServer: {
    port: 8081, // 端口得和主应用注册的一致
    headers: {
      'Access-Control-Allow-Origin': '*', // 允许跨域，不然主应用加载不了
    },
  },
  configureWebpack: {
    output: {
      library: `vue-subapp`, // 子应用的库名，唯一就行
      libraryTarget: 'umd', // 输出格式用 UMD，qiankun 能识别
      chunkLoadingGlobal: `webpackJsonp_vue-subapp`, // 避免和其他子应用的 webpack 冲突
    },
  },
};

4.2.3 改子应用的路由

子应用的路由得和主应用的 activeRule 对应上，打开 router/index.js：

javascript 复制代码

import { createRouter, createWebHistory } from 'vue-router';
import Home from '../views/Home.vue';

const routes = [
  {
    path: '/',
    name: 'Home',
    component: Home,
  },
];

// 被 qiankun 加载时，路由基础路径用主应用的 activeRule；单独运行时用 /
const router = createRouter({
  history: createWebHistory(window.__POWERED_BY_QIANKUN__ ? '/vue-subapp' : '/'),
  routes,
});

export default router;

五、第三步：跑起来看看效果

先启动主应用：

bash 复制代码

cd qiankun-main
npm run serve

再启动子应用：

bash 复制代码

cd qiankun-vue-subapp
npm run serve

打开浏览器访问 http://localhost:8080，点"Vue 子应用"，就能看到子应用被加载到主应用里啦~

六、进阶：子应用和主应用咋通信？

简单的通信可以直接用 props 传，比如主应用给子应用传数据，子应用也能给主应用发消息。

6.1 主应用给子应用传数据

改主应用 registerMicroApps 的配置：

javascript 复制代码

registerMicroApps([
  {
    name: 'vue-subapp',
    entry: '//localhost:8081',
    container: '#subapp-container',
    activeRule: '/vue-subapp',
    props: { // 要传给子应用的东西
      userInfo: { name: '我是主应用传的用户信息' },
      onMsgFromSubapp: (msg) => console.log('主应用收到子应用消息：', msg),
    },
  },
]);

6.2 子应用接收并给主应用发消息

子应用在 mount 钩子里就能拿到主应用传的东西：

javascript 复制代码

export async function mount(props) {
  console.log('子应用收到主应用的数据：', props.userInfo);
  // 子应用给主应用发消息
  props.onMsgFromSubapp('嘿，主应用！我是子应用~');
  render(props);
}

七、部署的时候要注意啥？

子应用部署 ：子应用打包后丢到静态服务器（比如 Nginx），主应用的 entry 要写子应用的线上地址；
跨域问题：生产环境得用 Nginx 反向代理，别让浏览器报跨域错；
资源路径 ：子应用的图片、CSS 这些资源尽量用相对路径，或者打包时配置 publicPath。

八、qiankun 常见问题排查清单

遇到问题先看这几个点：

问题现象	可能原因	解决办法
主应用加载子应用时白屏	子应用端口和主应用注册的不一致	检查子应用 `vue.config.js` 的 `port` 和主应用 `entry`
浏览器报跨域错误	子应用没开跨域	子应用 `devServer.headers` 加 `Access-Control-Allow-Origin: *`
子应用路由跳转404	子应用路由基础路径没配对	检查子应用路由的 `createWebHistory` 参数，要和主应用 `activeRule` 一致
多个子应用样式冲突	子应用样式没隔离	子应用加 `scoped` 样式，或用 CSS Modules
子应用单独运行正常，主应用加载后报错	子应用没暴露生命周期钩子	检查子应用 `main.js` 是否导出了 `bootstrap/mount/unmount`

🎯 2025年最新大厂前端场景面试题（完整题库+解析）

一份系统整理的前端专项面试资料，内容涵盖 JavaScript、React、Vue、Node.js、性能优化、工程化、浏览器原理、网络协议等高频考点，所有题目均来自大厂真实场景与近期面试趋势。

📚 资料详情

方向：前端开发

格式：PDF

页数：251页（含详细答案与扩展解析）

适用：面试冲刺、体系复盘、技术查漏

📥 获取方式

👉 夸克网盘链接：https://pan.quark.cn/s/bcf695cf5ede

（可直接下载，无需提取码）

qiankun 微前端应用入门教程：从搭建到部署