27.2 微前端方案在 Vue 项目中的落地

微前端是一种将前端应用分解为更小、更简单的独立模块的架构模式，每个模块可以由不同团队独立开发、测试和部署，最终组合成一个完整的应用。在 Vue 生态中，有两个主流的微前端框架实践最为广泛：qiankun 和 wujie。它们都允许你将多个 Vue 项目（甚至包含不同技术栈的子应用）组合成一个统一的产品，同时又保持各自的独立性与技术自由。

为什么需要微前端

在大型 Vue 项目中，随着业务膨胀和团队增多，单仓单体应用会逐渐暴露问题：

构建与部署慢：全量打包一次可能需要数分钟，改一行代码也要等待整个项目构建。
技术栈锁定：团队无法根据新需求选择更合适的框架，所有模块被限制在同一版本。
协作冲突：多人修改同一代码库，合并冲突频繁，发布时需要小心翼翼协调。
运行时耦合：一个模块的故障可能通过全局状态或样式污染导致整个应用崩溃。

微前端通过拆分应用解决了这些问题，但它也引入了新的复杂性，比如子应用如何加载、路由如何同步、沙箱隔离和通信等。好在 qiankun 和 wujie 已经提供了成熟的解决方案，Vue 项目接入它们非常顺畅。

qiankun 的落地实践

qiankun 是基于 single-spa 封装的微前端框架，提供了开箱即用的沙箱隔离、子应用生命周期管理和资源预加载。

1. 改造主应用（基座）
主应用通常是一个 Vue 项目，负责注册子应用并提供容器 DOM。安装 qiankun 后，在 main.js 中注册微应用：

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

// 注册子应用
registerMicroApps([
  {
    name: 'vue-sub-app',        // 子应用名称，需唯一
    entry: '//localhost:8081',  // 子应用地址
    container: '#subapp-container', // 子应用挂载的 DOM 容器
    activeRule: '/subapp',      // 路由激活规则
  }
]);

// 启动 qiankun
start();

// 主应用正常挂载 Vue 根实例
new Vue({
  render: h => h(App)
}).$mount('#app');

主应用的 index.html 中预留一个容器：

<div id="app"></div>
<!-- 子应用将挂载到这里 -->
<div id="subapp-container"></div>

2. 改造子应用
子应用需要在入口文件（通常为 main.js）中导出 qiankun 需要的生命周期函数，并修改 webpack 配置使其支持 umd 打包。在 Vue CLI 项目中，可以通过 @vue/cli-plugin-qiankun 插件自动处理。如果是 Vite 项目，则需要 vite-plugin-qiankun。

使用 vue-cli-plugin-qiankun 的示例：

// 子应用 main.js
import Vue from 'vue';
import App from './App.vue';
import { qiankunWindow, renderWithQiankun } from 'vite-plugin-qiankun/dist/helper';

let instance = null;

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

// 独立运行时直接渲染
if (!qiankunWindow.__POWERED_BY_QIANKUN__) {
  render();
}

export async function bootstrap() { /* 初始化 */ }
export async function mount(props) {
  render(props);
}
export async function unmount() {
  instance.$destroy();
  instance = null;
}

同时需要配置子应用打包格式为 UMD，以及允许跨域访问（开发环境 webpack-dev-server 需设置跨域头）。

3. 主子应用通信
qiankun 支持全局状态和事件通信。最轻量的方式是使用 props 传递主应用的 store 或 bus，但更统一的实践是通过 initGlobalState 创建全局状态池：

// 主应用
import { initGlobalState } from 'qiankun';
const actions = initGlobalState({ user: 'Alice' });
actions.onGlobalStateChange((state, prev) => {
  console.log('主应用状态变化', state);
});

// 子应用 mount 时接收 props 中的 onGlobalStateChange 和 setGlobalState
export async function mount(props) {
  props.onGlobalStateChange((state, prev) => {
    console.log('子应用监听到全局状态变化', state);
  });
  props.setGlobalState({ user: 'Bob' });
}

4. 样式隔离
qiankun 默认开启 strictStyleIsolation 使用 Shadow DOM 实现严格样式隔离，但这会让无法穿透 Shadow 的第三方组件弹出层渲染异常。更常用的是 experimentalStyleIsolation，通过给子应用容器包裹 data-qiankun 属性后重写样式选择器，实现“软隔离”。配置方法：

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

若还出现样式冲突，可以在子应用中使用 CSS Modules 或 BEM 命名规范，或者借助 postcss 插件自动添加前缀。

5. 公共依赖处理
如果多个子应用都使用 Vue 和 Element Plus 等大型库，可以通过 externals 将这些依赖剥离，由主应用统一加载。webpack 中配置：

// 子应用 vue.config.js
module.exports = {
  configureWebpack: {
    externals: {
      vue: 'Vue',
      'element-plus': 'ElementPlus'
    }
  }
};

主应用的 index.html 通过 CDN 提前引入这些库，避免重复打包。Vite 项目可以用 vite-plugin-externals。

wujie 的落地实践

wujie 是腾讯推出的一款基于 WebComponent 的微前端框架，天然实现了完美的沙箱隔离（样式、JS 作用域），且支持与 Iframe 混合。它接入更加简单，尤其适合希望“开箱即用”的 Vue 项目。

1. 主应用使用 Vue 组件方式引入子应用
wujie 提供了 Vue 组件 WujieVue，可以像普通组件一样在模板中嵌入子应用：

// 主应用 main.js
import WujieVue from 'wujie-vue3';
Vue.use(WujieVue);

<template>
  <WujieVue
    name="sub-app"
    url="//localhost:8081"
    sync="true" 
  />
</template>

sunc 属性可以把子应用的 URL 与主应用路由同步，实现路由联动。

2. 子应用无需改造
wujie 最大的优势是子应用可以零改动接入！无论是 Vue 2/3、React 还是纯 HTML，不需要导出生命周期函数，不需要更改打包配置。wujie 通过 Iframe + WebComponent 的方式将子应用包裹起来，天然保证了 JS 和 DOM 的隔离。但是，如果子应用需要与主应用通信或做一些生命周期的事情，可以安装 wujie 包并使用其 API。

3. 通信方式
wujie 提供 bus 事件总线进行主子和子应用间通信，简单直接：

// 主应用
import { bus } from 'wujie';
bus.$on('sub-app-event', (data) => console.log(data));
bus.$emit('main-event', 'hello from main');

// 子应用
window.$wujie?.bus.$on('main-event', (msg) => console.log(msg));
window.$wujie?.bus.$emit('sub-app-event', { foo: 'bar' });

4. 样式隔离与公共依赖
wujie 使用 WebComponent 天然隔离样式，外部样式不影响子应用，子应用样式不影响主应用，且不会出现像 qiankun experimentalStyleIsolation 下的一些弹出层定位问题。公共依赖方面，wujie 支持配置 plugins 和 fetch 钩子来修改子应用的 HTML，可以在加载时将公共 script 替换为主应用的缓存版本，或者通过 degrade 属性降级为真正的 iframe，隔离更彻底。

选型与实战建议

qiankun 更适合已经基于 single-spa 或对 qiankun 生命周期管理熟悉的团队，对子应用有一定改造要求，但提供了更精细的控制力。它的社区成熟，企业实践案例多。
wujie 更适合快速集成，追求“免改造”和极致样式隔离的场景。它的接入成本几乎为零，尤其当子应用是历史遗留且难以修改时，wujie 是不错的选择。

实战中的几个注意点：

路由同步：主应用和子应用路由最好设计成主应用一个前缀，比如 /app1 对应子应用 A。子应用内部路由使用 history 模式，但 base 要设置正确，避免与主应用路由冲突。
登录凭证同步：将 token 放在主应用的 localStorage 中，子应用通过 qiankun 的 props 或 wujie 的 bus 获取，或者子应用直接读取同域下的 localStorage（但需注意沙箱可能阻挡，qiankun 默认沙箱会隔离 localStorage，需要关闭或使用共享方式）。
公共组件复用：可以将主应用的组件库、工具函数通过 props 注入子应用，或者将二者发布为私有 npm 包在子应用中安装，但要注意版本一致性问题。
调试与监控：微前端增加了调用链长度，错误可能跨应用。推荐子应用接入同一套错误监控 SDK（如 Sentry），并在微前端框架提供的生命周期钩子中上报崩溃。

微前端不是银弹，它引入了额外的复杂度，仅在前端过于庞大、多团队并行开发且发布冲突严重时才值得使用。对于大多数中型项目，模块化良好的 Monorepo 往往就足够了。但当你需要微前端时，qiankun 和 wujie 这两个方案能让你的 Vue 项目平稳落地。