微前端架构开发秘籍：乾坤（Qiankun）全流程实战指南（保姆级）

# 主应用（Vue3 + Vite）
npm init vite@latest main-app -- --template vue
cd main-app
npm install qiankun

# 子应用（React18 + Vite）
npm init vite@latest sub-app -- --template react
cd sub-app
npm install qiankun

3.2 子应用配置详解

3.2.1 vite.config.js 配置

// sub-app/vite.config.js
export default defineConfig({
  plugins: [react()],
  base: '/sub-app', // 重要：设置正确的publicPath
  server: {
    port: 8081,
    headers: {
      'Access-Control-Allow-Origin': '*',
      'Cross-Origin-Embedder-Policy': 'require-corp',
      'Cross-Origin-Opener-Policy': 'same-origin'
    }
  }
});

3.2.2 生命周期实现

// sub-app/src/main.js
let root = null;

function render(props = {}) {
  const { container } = props;
  root = createRoot(container ? container.querySelector('#root') : document.getElementById('root'));
  root.render(
    <React.StrictMode>
      <App />
    </React.StrictMode>
  );
}

// 独立运行模式
if (!window.__POWERED_BY_QIANKUN__) {
  render();
}

export async function bootstrap() {
  console.log('[React App] bootstrap');
}

export async function mount(props) {
  console.log('[React App] mount', props);
  render(props);
}

export async function unmount() {
  console.log('[React App] unmount');
  root.unmount();
  root = null;
}

export async function update(props) {
  console.log('[React App] update', props);
}

3.3 主应用配置详解

3.3.1 路由配置

// main-app/src/router.js
import { createRouter, createWebHistory } from 'vue-router';

const routes = [
  {
    path: '/',
    component: () => import('./views/Home.vue')
  },
  {
    path: '/sub-app',
    component: () => import('./views/SubApp.vue')
  }
];

export const router = createRouter({
  history: createWebHistory(),
  routes
});

3.3.2 乾坤集成

<!-- main-app/src/views/SubApp.vue -->
<template>
  <div id="sub-app-container"></div>
</template>

<script setup>
import { registerMicroApps, start } from 'qiankun';
import { router } from '@/router';

// 动态加载子应用
router.beforeEach((to) => {
  if (to.path.startsWith('/sub-app')) {
    registerMicroApps([
      {
        name: 'react-sub-app',
        entry: '//localhost:8081',
        container: '#sub-app-container',
        activeRule: '/sub-app',
        props: {
          theme: 'dark',
          user: { id: 123, name: 'John' }
        }
      }
    ]);
    start({ prefetch: true });
  }
});
</script>

四、高级特性实战

4.1 预加载优化

// 主应用配置
start({
  prefetch: {
    type: 'all', // 可选：all | visible | none
    priority: ['sub-app']
  }
});

4.2 样式隔离配置

// 子应用添加Shadow DOM支持
// sub-app/src/main.js
function render(props) {
  const shadowRoot = props.container.attachShadow({ mode: 'open' });
  shadowRoot.innerHTML = `
    <div id="root"></div>
    <style>
      /* 子应用样式 */
    </style>
  `;
  // ... 渲染逻辑
}

4.3 通信实现案例

4.3.1 主应用向子应用传参

// 主应用注册时传递props
registerMicroApps([
  {
    // ... 其他配置
    props: {
      user: { id: 123, name: 'John' }
    }
  }
]);

// 子应用接收
function App() {
  const props = useContext(qiankunContext);
  return <div>User: {props.user.name}</div>;
}

4.3.2 子应用触发事件

// 子应用触发事件
qiankun.loadedMicroApp('main-app').emit('user-login', { token: 'xxx' });

// 主应用监听事件
registerMicroApps([
  {
    // ... 其他配置
    lifecycle: {
      afterMount: app => {
        app.on('user-login', (data) => {
          // 处理登录事件
        });
      }
    }
  }
]);

五、生产环境部署建议

5.1 Nginx 配置示例

server {
  listen 80;
  server_name main-app.com;

  location / {
    proxy_pass http://localhost:8080;
    proxy_set_header Host $host;
  }

  location /sub-app {
    proxy_pass http://localhost:8081;
    proxy_set_header Host $host;
  }
}

5.2 性能优化策略

懒加载配置：

start({
  prefetch: {
    type: 'visible',
    exclude: ['sub-app']
  }
});

2、资源压缩：

// vite.config.js
build: {
  minify: 'esbuild',
  sourcemap: false
}

缓存策略：

location /static {
  expires 7d;
  add_header Cache-Control "public, immutable";
}

六、常见问题解决方案

6.1 样式冲突排查

检查是否启用 CSS 沙箱：

start({
  sandbox: {
    experimentalStyleIsolation: true
  }
});

2、使用 Shadow DOM 强制隔离

6.2 跨域问题解决

子应用设置正确的 CORS headers
主应用使用@umijs/plugin-qiankun自动处理

6.3 路由冲突处理

子应用配置独立路由前缀：

// React子应用
import { createBrowserHistory } from 'history';
export const history = createBrowserHistory({ basename: '/sub-app' });

七、总结与展望

通过乾坤微前端架构，我们可以实现：

多团队并行开发互不干扰
技术栈自由选择与渐进式升级
独立部署与回滚能力
更优的用户体验（预加载、按需加载）

未来发展方向：

增强沙箱能力（WebAssembly 支持）
智能资源管理（动态预加载策略）
服务端渲染（SSR）支持
跨框架状态管理方案

点赞收藏不迷路，技术成长有速度！

魔乐社区

魔乐社区（Modelers.cn) 是一个中立、公益的人工智能社区，提供人工智能工具、模型、数据的托管、展示与应用协同服务，为人工智能开发及爱好者搭建开放的学习交流平台。社区通过理事会方式运作，由全产业链共同建设、共同运营、共同享有，推动国产AI生态繁荣发展。

更多推荐

小参数・大码力・易部署 | Qwen3.6-27B上线魔乐社区，基于昇腾的部署教程来了

继一周前模型开源发布后，千问再度开源Qwen3.6-27B —— 一个拥有270亿参数的稠密多模态模型，也是社区呼声最高的模型规格。Qwen3.6-27B 依然支持多模态思考与非思考模式，在智能体编程方面达到了旗舰级表现，全面超越前代开源旗舰 Qwen3.5-397B-A17B（总参数397B / 激活参数17B的MoE模型）。作为稠密架构，它无需MoE路由即可部署，是开发者在实用、可广泛部署规模