当我们面对一个庞大的单体前端系统时往往会有种“压在胸口的石头”般的沉重感。页面卡顿、代码难以维护、团队协作摩擦不断……这些痛点像雨后春笋一样层出不穷。微前端的出现，为这些困境提供了一把钥匙，而其中Zui火热的实现方案之一——qiankun，geng像是一位经验丰富的老匠人，帮你把碎片化的业务拼装成一幅完整的画卷。

下面我将用一种略带戏剧性的笔触，把从零开始到上线部署的全流程拆解出来让你在半小时内拥有自己的微前端实验室。

先抛出几个真实场景：

电商平台同一页面需要展示搜索、商品列表、购物车三个完全不同技术栈的子系统。

金融后台想把旧版 Angular 模块平滑迁移到 React，却不想一次性 所有代码。

多团队并行开发，每个团队dou有自己的发布节奏和 CI/CD 流程。

面对上述需求，传统单体架构只Neng让你头疼不Yi，而 qiankun 则提供了：

独立部署：每个子应用Ke以单独上线、回滚，不会牵连全局。

技术无关：React、Vue、Angular…只要Neng输出浏览器可运行的资源，douNeng挂进来。

统一治理：主应用负责路由切换、全局状态与安全校验，子应用专注业务本身。

一句话概括：让大块头变成灵活的小部件，让团队协作geng像拼图而不是拔河。

它是整个系统的大门，负责注册子系统、渲染容器以及统一路由。想象它是一位“大厨”，所有配料dou由它调度，却不亲自下锅烹饪。

每个子模块dou是一个“小餐厅”，拥有自己的菜单、厨房和服务员。只要入口地址对了它们就Neng自行开张或收摊。

bootstrap → mount → unmount → update

bootstrap：第一次加载时执行，仅一次用来准备全局资源。

mount：每次进入该子系统时调用，用于渲染 UI。

unmount：离开时销毁 DOM 与事件监听，防止泄漏。

update：热geng新或参数变动时触发。

Props 直传：`主壳 → 子模块` 的Zui简路径，一次性把数据塞进去。

全局状态：`initGlobalState` 创建共享对象，实现双向同步。

事件总线：`window.eventBus` 或自定义 Pub/Sub，让任意模块随意广播消息。

# 主壳目录
mkdir main-shell && cd main-shell
npm init -y
npm i qiankun webpack webpack-cli webpack-dev-server html-webpack-plugin -D
# 子应用示例：React + Vue
npx create-react-app react-micro
npm i -g @vue/cli && vue create vue-micro

micro-project/
│
├─ main-shell/
│   ├─ src/
│   │   ├─ index.html
│   │   ├─ index.js          # 主入口
│   │   └─ router.js         # 路由管理器
│   └─ webpack.config.js
│
├─ react-micro/
│   └─ src/...
│   └─ webpack.config.js
│
└─ vue-micro/
    └─ src/...
    └─ vue.config.js

// main-shell/src/index.js
import { registerMicroApps, start } from 'qiankun';
// 注册两个子系统，这里使用本地 devServer 地址Zuo演示
registerMicroApps();
// 启动 qiankun —— 单实例模式确保一次只Neng挂载一个子系统
start;

`index.html` 中预留一个容器供子系统渲染：

// main-shell/src/router.js 
window.addEventListener => location.reload);
document.querySelectorAll.forEach(a => {
  a.addEventListener('click', e => {
     e.preventDefault;
     const path = a.getAttribute;
     history.pushState;
     location.reload; // 简单粗暴刷新触发 qiankun 自动挂载逻辑
  });
});

// react-micro/src/public-path.js
if  {
  // 当被 qiankun 包裹时需要使用注入的 publicPath 防止资源路径错位。
  __webpack_public_path__ = window.__INJECTED_PUBLIC_PATH_BY_QIANKUN__;
}
// react-micro/src/index.js
import './public-path';
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';
let root = null;
function render {
  const { container } = props;
  const dom = container ? container.querySelector : document.getElementById;
  if  root = ReactDOM.createRoot;
  root.render;
}
// 独立启动时直接渲染页面以便本地调试。
if  {
  render;
}
// 生命周期导出供主壳调用。
export async function bootstrap { console.log; }
export async function mount { console.log; render; }
export async function unmount { 
  if  { root.unmount; root = null;}
}
export async function update { console.log; }

// react-micro/webpack.config.js
const { name } = require;
module.exports = {
  output:{
      library:`${name}-`,
      libraryTarget:'umd',
      chunkLoadingGlobal:`webpackJsonp_${name}`
  },
  devServer:{
      port:3001,
      headers:{'Access-Control-Allow-Origin':'*'}
  }
};

// vue-micro/src/public-path.js 同上
// vue-micro/src/main.js 
import './public-path';
import { createApp } from 'vue';
import App from './App.vue';
let instance = null;
function render {
   const { container } = props;
   const el = container ? container.querySelector : document.getElementById;
   if  instance = createApp;
   instance.mount;
}
if  {
   render;
}
export async function bootstrap{ console.log; }
export async function mount{ console.log; render; }
export async function unmount{ if{ instance.unmount; instance=null;} }
export async function update{ console.log; }

// vue-micro/vue.config.js 
module.exports = {
   publicPath: process.env.NODE_ENV === 'production' ? '/micro-vue/' : '/',
   configureWebpack:{
       output:{
           library:'-',
           libraryTarget:'umd',
           jsonpFunction:`webpackJsonp_${require.name}`
       },
       devServer:{port:3002,headers:{'Access-Control-Allow-Origin':'*'}}
   }
};

`qiankun` 本身只负责激活规则，我们仍需要自己解析参数。下面给出一个简易实现，用正则提取占位符并返回 params 对象。

// utils/routeMatcher.js 
export function match{
   for{
       const pattern='^'+r.path.replace')+'$';
       const m=pathname.match);
       if{
           const keys=r.path.match||;
           const params={};
           keys.forEach=>params=m);
           return {...r,params};
       }
   }
   return null;
}
const routes=;
console.log);
/*=> {path:'/product/:cat/:id',micro:'product-app',params:{cat:'electronics',id:'123'}} */

// 主壳初始化全局状态 
import { initGlobalState } from 'qiankun';
const actions = initGlobalState;
actions.onGlobalStateChange=>{ 
     console.log;
});
// 将方法注入子应用 
registerMicroApps();

`react` 子应用拿到 `props` 后即可直接调用 `setGlobalState` 来geng新，全局监听会自动推送给其他Yi经挂载的模块，实现类似 Redux 的跨域同步效果，却无需额外库。

// event-bus.js 
class EventBus{
 constructor{ this.handlers={};}
 on{ .push;}
 emit{ .forEach);}
 off{ this.handlers= .filter;}
}
window.__EVENT_BUS__=new EventBus;
// 示例：在某个子模块中发布消息 
window.__EVENT_BUS__.emit;
// 在另一模块中订阅 
window.__EVENT_BUS__.on);

AOP 思维hen重要：所有副作用尽量放在生命周期或事件总线里而不是直接修改 DOM；这样才Neng保持各模块相互独立而不互相踩脚趾。

#CSS 隔离一定要Zuo！推荐使用 CSS Module + BEM 命名，即使是同一套 UI 库，也Neng避免 “蓝色按钮被红色覆盖” 的尴尬场面。

#错误捕获不可省略。Ke以在每个子应用Zui外层套上一层 React/Vue 错误边界，把异常上报至统一监控平台，如 Sentry 或自建日志服务。

#预加载策略视业务而定。Ru果某些高频页面如“购物车”“个人中心”经常被访问，可在主壳 `start` 提前拉取对应资源，提升首屏体验。

#CDN 部署别忘记加缓存控制头部；尤其是 `.js.map` 文件，在生产环境关闭 sourceMap 防止泄露内部实现细节。

#版本管理Zui好采用 Git Submodule 或者 monorepo 中的 workspace，将公共依赖抽离到根目录，避免不同微应用重复下载同一个库导致体积膨胀。

SOS 场景：a 微应用里直接写了 `window.userInfo={}`；随后 b 微应用读取该变量却发现值被覆盖，引发异常崩溃。

解决思路：

CamelCase 前缀化，例如 `__APP_A_userInfo__`；Zui好统一通过 `window.__MICRO_APP_GLOBALS__` 对象集中管理。

开启 Qiankun 沙箱模式： javascript start; 严格样式隔离还Neng阻止 CSS 泄漏。

若仍需全局变量，请使用 IIFE 包裹并强制 `'use strict';` ，让变量只Neng在函数作用域内生效。