Qiankun微前端框架实战教程：从零构建主应用与微应用

2026-02-04 05:19:13作者：胡易黎Nicole

前言

微前端架构正在成为大型前端应用开发的主流模式之一，而Qiankun作为一款优秀的微前端解决方案，提供了完整的微前端实现方案。本文将详细介绍如何使用Qiankun框架从零开始构建一个完整的微前端项目，包含主应用和各类微应用的配置方法。

主应用搭建

主应用作为微前端的容器，主要负责微应用的注册和管理。Qiankun对主应用的技术栈没有限制，可以是任何前端框架或原生JavaScript项目。

安装依赖

首先需要安装Qiankun核心库：

npm install qiankun --save
# 或
yarn add qiankun

注册微应用

在主应用中注册微应用非常简单，只需要提供微应用的基本信息和挂载容器：

import { registerMicroApps, start } from 'qiankun';

registerMicroApps([
  {
    name: 'angularApp',       // 微应用名称
    entry: '//localhost:4200', // 微应用入口地址
    container: '#container',   // 挂载容器选择器
    activeRule: '/app-angular' // 激活规则
  },
  {
    name: 'reactApp',
    entry: '//localhost:3000',
    container: '#container',
    activeRule: '/app-react'
  },
  {
    name: 'vueApp',
    entry: '//localhost:8080',
    container: '#container',
    activeRule: '/app-vue'
  }
]);

// 启动Qiankun
start();

微应用配置

微应用需要根据不同的技术栈进行相应配置，主要分为基于Webpack构建的应用和非Webpack构建的应用两种情况。

通用配置要点

无论使用哪种技术栈，微应用都需要注意以下几点：

运行时publicPath：需要动态设置资源加载路径
路由配置：建议使用history模式，并设置正确的base路径
生命周期：导出bootstrap、mount和unmount三个生命周期函数
Webpack配置：需要支持UMD格式打包和跨域访问

React微应用配置

以create-react-app创建的React 16项目为例：

添加public-path.js文件：

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

配置路由base：

<BrowserRouter basename={window.__POWERED_BY_QIANKUN__ ? '/app-react' : '/'}>

修改入口文件：

import './public-path';
import React from 'react';
import ReactDOM from 'react-dom';

function render(props) {
  const { container } = props;
  ReactDOM.render(
    <App />,
    container ? container.querySelector('#root') : document.querySelector('#root')
  );
}

export async function mount(props) {
  render(props);
}

export async function unmount(props) {
  const { container } = props;
  ReactDOM.unmountComponentAtNode(
    container ? container.querySelector('#root') : document.querySelector('#root')
  );
}

修改Webpack配置（使用rescripts）：

module.exports = {
  webpack: (config) => {
    config.output.library = `${name}-[name]`;
    config.output.libraryTarget = 'umd';
    config.output.globalObject = 'window';
    return config;
  },
  devServer: (config) => {
    config.headers = {
      'Access-Control-Allow-Origin': '*'
    };
    return config;
  }
};

Vue微应用配置

以Vue CLI创建的Vue 2项目为例：

添加public-path.js文件（同React）
修改入口文件：

let router = null;
let instance = null;

function render(props = {}) {
  const { container } = props;
  router = new VueRouter({
    base: window.__POWERED_BY_QIANKUN__ ? '/app-vue/' : '/',
    mode: 'history',
    routes
  });

  instance = new Vue({
    router,
    render: h => h(App)
  }).$mount(container ? container.querySelector('#app') : '#app');
}

export async function mount(props) {
  render(props);
}

export async function unmount() {
  instance.$destroy();
  instance.$el.innerHTML = '';
  instance = null;
  router = null;
}

修改vue.config.js：

module.exports = {
  devServer: {
    headers: {
      'Access-Control-Allow-Origin': '*'
    }
  },
  configureWebpack: {
    output: {
      library: `${name}-[name]`,
      libraryTarget: 'umd'
    }
  }
};

Angular微应用配置

以Angular CLI 9创建的Angular项目为例：

添加public-path.js文件（同React/Vue）
配置路由base：

@NgModule({
  providers: [
    { provide: APP_BASE_HREF, 
      useValue: window.__POWERED_BY_QIANKUN__ ? '/app-angular' : '/' }
  ]
})

修改入口文件：

let app: void | NgModuleRef<AppModule>;

async function render() {
  app = await platformBrowserDynamic()
    .bootstrapModule(AppModule)
    .catch(err => console.error(err));
}

export async function mount() {
  render();
}

export async function unmount() {
  // @ts-ignore
  app.destroy();
}

修改Webpack配置（使用@angular-builders/custom-webpack）

非Webpack构建的微应用

对于jQuery等传统项目，只需导出生命周期函数：

((global) => {
  global['purehtml'] = {
    bootstrap: () => Promise.resolve(),
    mount: () => {
      $('#container').html('Hello World');
      return Promise.resolve();
    },
    unmount: () => Promise.resolve()
  };
})(window);