微前端 — Micro Frontend

1. 核心概念与动机

定义

微前端是将前端应用拆分为多个独立子应用，每个子应用可独立开发、测试、部署，运行时通过容器动态聚合为完整应用。核心原则：技术栈无关、独立仓库、独立生命周期、自治团队。

解决的问题

适用场景

• 后台管理系统：多业务线聚合（CMS/订单/用户/支付各自独立团队）
• 大型 C 端应用：多团队并行迭代（首页/搜索/详情/个人中心独立发布）
• 渐进式技术改造：新功能用新框架（React 18 / Vue 3），老系统保持不动
• B2B 可组合平台：不同客户选择不同模块组合（如电商平台功能开关）

2. 主流方案详解

2.1 qiankun（阿里，基于 single-spa）

架构原理

主应用 ──注册→ 子应用列表（activeRule ↔ name ↔ entry）
   │
   ├─ 路由变化匹配 activeRule
   ├─ HTML Entry 加载子应用 HTML → 解析出 JS/CSS
   ├─ 创建 JS 沙箱 + CSS 隔离
   ├─ 执行生命周期: bootstrap → mount → unmount → update
   └─ 渲染到指定 DOM 容器 (#app)

主应用注册代码

// apps/main/src/micro/index.ts
import { registerMicroApps, start, initGlobalState } from 'qiankun';
import type { ObjectType } from '@qiankunjs/core';

interface AppConfig {
  name: string;
  entry: string;          // 子应用 HTML 地址
  container: string;      // 挂载 DOM 选择器
  activeRule: string;     // 路由前缀匹配
  props?: ObjectType;     // 传递给子应用的数据
}

const apps: AppConfig[] = [
  {
    name: 'app-order',
    entry: '//localhost:3001',
    container: '#sub-app-container',
    activeRule: '/order',
    props: { baseUrl: '/order' },
  },
  {
    name: 'app-user',
    entry: '//localhost:3002',
    container: '#sub-app-container',
    activeRule: '/user',
  },
];

registerMicroApps(apps, {
  beforeLoad: [async (app) => console.log('[qiankun] before load', app.name)],
  beforeMount: [async (app) => console.log('[qiankun] before mount', app.name)],
  afterMount: [async (app) => console.log('[qiankun] after mount', app.name)],
  beforeUnmount: [async (app) => console.log('[qiankun] before unmount', app.name)],
  afterUnmount: [async (app) => console.log('[qiankun] after unmount', app.name)],
});

// 启动（可配置 prefetch / sandbox / singular 等）
start({ sandbox: { experimentalStyleIsolation: true }, prefetch: 'all' });

子应用入口（以 Umi 为例）

// apps/order/src/app.ts
export const qiankun = {
  async bootstrap() {
    console.log('order app bootstraped');
  },
  async mount(props: any) {
    render(props); // props 含 container/onGlobalStateChange/setGlobalState
  },
  async unmount(props: any) {
    ReactDOM.unmountComponentAtNode(props.container ? props.container.querySelector('#root')! : document.getElementById('root'));
  },
};

生命周期

beforeLoad → bootstrap → beforeMount → mount → afterMount
                                    ↓ (路由失活)
                      beforeUnmount → unmount → afterUnmount

CSS 隔离

JS 沙箱

// SnapshotSandbox 简版示意
class SnapshotSandbox {
  private snapshot: Record<string, any> = {};
  private modifiedProps: Record<string, any> = {};

  activate() {
    this.snapshot = {};
    for (const key in window) {
      this.snapshot[key] = window[key]; // 保存快照
    }
    Object.assign(window, this.modifiedProps); // 恢复上次修改
  }

  deactivate() {
    for (const key in window) {
      if (window[key] !== this.snapshot[key]) {
        this.modifiedProps[key] = window[key]; // 记录差异
        window[key] = this.snapshot[key];       // 恢复快照
      }
    }
  }
}

通信机制：initGlobalState

// 主应用
const { onGlobalStateChange, setGlobalState } = initGlobalState({ user: null, token: '' });

onGlobalStateChange((state, prev) => {
  console.log('[qiankun] global state changed', state, prev);
});

setGlobalState({ user: { id: 1, name: 'admin' }, token: 'xxx' });

// 子应用
props.onGlobalStateChange((state, prev) => { /* 同步 */ }, true); // true = 立即触发
props.setGlobalState({ /* 局部更新 */ });

预加载 prefetch

start({
  prefetch: 'all',           // 所有子应用
  prefetch: ['app-order'],   // 指定列表
  prefetch: true,            // 第一个子应用加载完后预加载其余
});

常见坑

2.2 Module Federation（Webpack 5 / Rspack）

核心概念

配置详解

// apps/remote/webpack.config.js —— Remote 生产者
const { ModuleFederationPlugin } = require('webpack').container;

module.exports = {
  output: { publicPath: 'http://localhost:3001/' },
  plugins: [
    new ModuleFederationPlugin({
      name: 'order',
      filename: 'remoteEntry.js',
      exposes: {
        './OrderList': './src/pages/OrderList',
        './OrderDetail': './src/pages/OrderDetail',
        './store': './src/store',
      },
      shared: {
        react: { singleton: true, requiredVersion: '^18.0.0' },
        'react-dom': { singleton: true, requiredVersion: '^18.0.0' },
        'react-router-dom': { singleton: true },
      },
    }),
  ],
};

// apps/host/webpack.config.js —— Host 消费者
module.exports = {
  plugins: [
    new ModuleFederationPlugin({
      name: 'shell',
      remotes: {
        order: 'order@http://localhost:3001/remoteEntry.js',
      },
      shared: {
        react: { singleton: true, requiredVersion: '^18.0.0' },
        'react-dom': { singleton: true, requiredVersion: '^18.0.0' },
      },
    }),
  ],
};

// apps/host/src/App.tsx —— 使用 Remote 模块
const OrderList = React.lazy(() => import('order/OrderList'));

function App() {
  return (
    <React.Suspense fallback={<Spin />}>
      <OrderList />
    </React.Suspense>
  );
}

加载原理

Host 运行时执行:
  import('order/OrderList')
    → 动态创建 <script src="http://localhost:3001/remoteEntry.js">
    → remoteEntry.js 自执行，在 __webpack_modules__ 注册所有 exposes 模块
    → 检查 shared 作用域: react/react-dom 版本是否满足 → 不满足则加载 Remote 的副本
    → 返回 OrderList 模块 → Host 渲染

shared 关键属性

shared: {
  react: {
    singleton: true,       // 强制全局只有一个 React 实例
    requiredVersion: '^18.0.0', // 版本约束，不满足时 console.warn
    eager: true,           // 立即加载（非懒加载，首屏可用）
    strictVersion: true,   // 版本不匹配时直接抛错
    shareScope: 'default', // 共享作用域名称，多组隔离用
  },
}

Module Federation vs qiankun 本质区别

Rspack Module Federation

Rspack 的 MF 实现与 Webpack MF 配置完全兼容，仅需替换插件包名：

// rspack.config.js —— 与 webpack 配置几乎一致
const { ModuleFederationPlugin } = require('@module-federation/enhanced/rspack');
// 或 rspack 内置: rspack.ModuleFederationPlugin

优势：构建速度提升 5-10x（Rust 编写）、HMR 更快、配置对齐 Webpack 生态。

常见坑

// 降级处理
function OrderPage() {
  return (
    <ErrorBoundary fallback={<Alert message="订单模块加载失败，请刷新重试" type="error" />}>
      <React.Suspense fallback={<Skeleton active />}>
        <OrderList />
      </React.Suspense>
    </ErrorBoundary>
  );
}

2.3 wujie（腾讯）

核心思路

iframe + Web Component 混合方案。子应用运行在 iframe 中（天然硬隔离），通过 Web Component 自定义元素挂载到主应用 DOM 树。

主应用 DOM
  └─ <wujie-app name="order" url="http://localhost:3001">
       └─ #shadow-root (Web Component)
            └─ <iframe srcdoc="...">
                 └─ 子应用完整运行环境（window/document/location 全部隔离）

使用方式

// 主应用
import { Wujie } from 'wujie-react';

function App() {
  const [show, setShow] = useState(true);
  return (
    <Wujie
      name="order"
      url="//localhost:3001"
      alive={true}                    // 保活模式（keep-alive，切回时不重新加载）
      props={{ user: { id: 1 } }}     // 传递数据
      sync={true}                     // 同步路由
      fetch={customFetch}             // 自定义 fetch（用于鉴权 header 注入）
      beforeLoad={/* ... */}
      beforeMount={/* ... */}
    />
  );
}

硬隔离 vs 软隔离

通信

// props 传参
<Wujie name="order" url="..." props={{ token: 'xxx' }} />

// 主 → 子
wujieBus.$emit('order:refresh', { id: 1 });

// 子 → 主（子应用内）
window.$wujie?.bus.$emit('global:logout');
// 或
window.$wujie?.props.methods.someCallback(data);

2.4 micro-app（京东）

核心思路

类 Web Component 思想，使用 CustomElement + Shadow DOM 接入子应用。接入成本极低，类似 iframe 的无缝替换体验。

<!-- 主应用直接使用自定义标签加载子应用 -->
<micro-app
  name="order"
  url="http://localhost:3001"
  baseroute="/order"
  disabledScopecss={false}
  iframe={false}
></micro-app>

子应用

// 子应用入口处（如 main.js）
if (window.__MICRO_APP_ENVIRONMENT__) {
  // 微前端环境下设置 publicPath 和路由 base
  __webpack_public_path__ = window.__MICRO_APP_PUBLIC_PATH__;
}

生命周期

document.querySelector('micro-app[name="order"]')?.addEventListener('mounted', (e) => {
  console.log('order app mounted', e);
});

通信

// 主 → 子
microApp.setData('order', { type: 'newMsg', data: { hello: 'world' } });

// 子 → 主
window.microApp?.dispatch({ type: 'logout' });

特点

• 接入成本最低：一行自定义标签即可加载子应用
• Shadow DOM 可选：开启后 CSS 隔离效果好，但兼容 antd 等 appendToBody 弹窗需配置
• iframe 降级：iframe={true} 可回退到 iframe 模式

2.5 四方案对比表

3. 关键实战问题

3.1 公共依赖处理

经验法则：

• 同框架同版本 → externals 或 shared（省体积）
• 同框架不同版本 → shared singleton 限制版本范围，或各自打包（省心但费体积）
• 不同框架 → 各自打包，无共享

3.2 样式隔离方案

// postcss.config.js —— 自动加前缀
module.exports = {
  plugins: [
    require('postcss-prefix-selector')({
      prefix: '.app-order',
      transform(prefix, selector, prefixedSelector) {
        // 保留 :root / :global 开头的选择器
        if (selector.startsWith(':root') || selector.startsWith(':global')) {
          return selector;
        }
        return prefixedSelector;
      },
    }),
  ],
};

3.3 登录态与鉴权

主应用
  ├─ 统一登录页面 → 获取 JWT Token
  ├─ Token 存入 localStorage（约定 key: AUTH_TOKEN）
  ├─ 子应用加载时通过 props / postMessage 透传
  └─ Token 刷新：主应用定时刷新后同步给所有子应用

问题点:
  ├─ Cookie SameSite 策略（Chrome 默认 Lax 会拦截 iframe 内 Cookie）
  ├─ SSO 单点登录（子应用各自跳转 SSO 时需统一回跳地址）
  └─ Token 过期同步（子应用检测 401 → 通知主应用刷新 → 重试请求）

// 主应用统一 token 刷新逻辑
let isRefreshing = false;
let failedQueue: Array<{resolve: Function; reject: Function}> = [];

function refreshToken(): Promise<string> {
  return axios.post('/api/auth/refresh', { refreshToken: storage.get('REFRESH_TOKEN') });
}

// axios 响应拦截器
axios.interceptors.response.use(
  (res) => res,
  async (error) => {
    if (error.response?.status !== 401) return Promise.reject(error);
    if (!isRefreshing) {
      isRefreshing = true;
      try {
        const { token } = await refreshToken();
        storage.set('AUTH_TOKEN', token);
        // 同步给所有子应用
        microApps.forEach((app) => app.setGlobalState?.({ token }));
        isRefreshing = false;
        failedQueue.forEach(({ resolve }) => resolve(token));
        failedQueue = [];
        return axios(error.config);
      } catch {
        isRefreshing = false;
        failedQueue.forEach(({ reject }) => reject(error));
        failedQueue = [];
        // 跳转登录页
      }
    } else {
      return new Promise((resolve, reject) => {
        failedQueue.push({ resolve, reject });
      });
    }
  },
);

3.4 子应用缓存策略

# HTML 入口不缓存
location /order {
  add_header Cache-Control "no-cache, must-revalidate";
  try_files $uri /order/index.html;
}

# 静态资源长期缓存
location /order/static {
  add_header Cache-Control "public, max-age=31536000, immutable";
}

3.5 错误处理与降级

// ErrorBoundary 包裹子应用容器
class SubAppErrorBoundary extends React.Component<{name: string}, {hasError: boolean}> {
  state = { hasError: false };

  static getDerivedStateFromError() {
    return { hasError: true };
  }

  componentDidCatch(error: Error) {
    console.error(`[SubApp] ${this.props.name} 渲染异常`, error);
    // 上报监控
  }

  render() {
    if (this.state.hasError) {
      return (
        <Result
          status="error"
          title={`${this.props.name} 模块加载异常`}
          extra={<Button onClick={() => this.setState({ hasError: false })}>重试</Button>}
        />
      );
    }
    return this.props.children;
  }
}

// qiankun 加载超时处理
registerMicroApps(apps, {
  beforeLoad: [async (app) => {
    const timeout = 10000;
    return Promise.race([
      Promise.resolve(),
      new Promise((_, reject) => setTimeout(() => reject(new Error(`加载超时 ${app.name}`)), timeout)),
    ]);
  }],
});

3.6 性能优化

// qiankun 预加载 + 手动控制
import { prefetchApps } from 'qiankun';

// 首屏加载完成后，空闲时预加载高频子应用
window.requestIdleCallback(() => {
  prefetchApps([
    { name: 'order', entry: '//localhost:3001' },
    { name: 'user', entry: '//localhost:3002' },
  ]);
});

4. 微前端 vs 替代方案

什么时候不需要微前端

• 小团队（<10人）：单体应用足够，微前端反而增加架构复杂度
• 单一业务线：无多团队协作冲突，模块化 + Monorepo 即可
• 技术栈统一：无渐进升级需求，Monorepo 共享 lint/CI/测试更高效
• 构建速度未成瓶颈：5 分钟内的构建不值得引入运行时开销

替代方案对比

决策树

需要拆前端么？
├─ 小团队 / 单一业务 / 构建 < 3min → 不需要，Monorepo 或模块化即可
└─ 多团队 / 多业务线 / 构建 > 5min
   ├─ 是否要求独立部署？
   │  ├─ 否 → Monorepo + 模块化
   │  └─ 是
   │     ├─ 是否技术栈无关？
   │     │  ├─ 否（全部 React） → Module Federation（模块级）或 qiankun（应用级）
   │     │  └─ 是
   │     │     ├─ 安全隔离要求高？→ wujie（iframe 硬隔离）
   │     │     ├─ 接入成本优先？→ micro-app（一行标签）
   │     │     └─ 生态成熟优先？→ qiankun（社区资源最多）
   │     └─ 还需要考虑
   │        ├─ 组件级共享 > 应用级组合 → Module Federation
   │        └─ 需要 IE11 兼容 → qiankun（SnapshotSandbox）

5. 参考资源

• qiankun 官方文档
• Module Federation 官方示例
• wujie 官方文档
• micro-app 官方文档
• Webpack Module Federation 原理
• Rspack Module Federation