@xingtukeji/micro

基于 Vue 3 和 iframe 的微前端容器，支持应用注册、空闲预加载、保活切换、主子应用路由同步和生命周期通知。

安装

pnpm add @xingtukeji/micro

主应用接入

插件必须在 Pinia 等 token 依赖初始化完成后安装，并在 Host 挂载前注册所有子应用：

// menu: [
//   {
//     title: "预加载子应用",
//     type: "micro",
//     microOptions: {
//       url: "http://127.0.0.1:12001",
//       name: "childapp",
//       preload: true,
//       keepAlive: true,
//     },
//   },
// ]

import xtMicro, { setupApp } from "@xingtukeji/micro";

app.use(xtMicro);

function traverseMenu(menu: any[]) {
  menu.forEach((item) => {
    if (item.type === "micro") {
      setupApp({
        ...item.microOptions,
        token: () => useUserStore().token,
        params: item.microOptions?.params ?? {},
      });
    }
    if (item.children) traverseMenu(item.children);
  });
}

traverseMenu(window.$config.menus);

setupApp 配置：

| 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | name | string | 必填 | 应用唯一名称 | | url | string | 必填 | 子应用入口地址，支持相对地址 | | preload | boolean | false | 浏览器空闲时预加载 | | keepAlive | boolean | false | 切换离开后保留 iframe 和子应用内存状态 | | sync | boolean | true | 将子应用路由同步到主应用 URL | | token | string \| () => string | - | 注入子应用 URL 的 token | | params | Record<string, any> | {} | 注入子应用 URL 的查询参数 | | onLoad / onUnload / onError | (event, app) => void | - | iframe 生命周期回调 |

挂载 Host

推荐把 XTMicroHost 放在不会被路由销毁的布局中：

<script setup lang="ts">
import { computed } from "vue";
import { useRoute } from "vue-router";
import { XTMicroHost } from "@xingtukeji/micro";

const route = useRoute();
const activeMicroApp = computed(() =>
  route.name === "micro" ? String(route.params.appId) : undefined
);
</script>

<template>
  <div class="content">
    <XTMicroHost :active-app="activeMicroApp" />
    <router-view v-show="!activeMicroApp" />
  </div>
</template>

<style>
.content {
  position: relative;
  min-width: 0;
  min-height: 0;
}
</style>

preload 与 keepAlive 相互独立：preload: true 只表示浏览器空闲时提前加载（单个应用最多等待 15 秒）；keepAlive: true 才会在切换离开后保留 iframe，并向子应用发送激活/失活通知。

setupApp({
  name: "kept-app",
  url: "http://127.0.0.1:12001",
  preload: true,
  keepAlive: true,
});

setupApp({
  name: "fresh-app",
  url: "http://127.0.0.1:12002",
  keepAlive: false,
});

保活会占用对应 iframe 的内存。刷新页面、调用 reloadApp() 或卸载 XTMicroHost 仍会重建 iframe，内存状态不会保留；需要跨刷新保存的数据应由子应用自行持久化。

XTMicroView 仅用于兼容旧接入方式：

<XTMicroView :app-id="appId" />

它会在组件卸载时销毁 iframe，不提供预加载和保活能力。

子应用接入

在创建 Vue 应用时调用 microInit。该方法在普通独立访问时也可安全调用：

import { microInit } from "@xingtukeji/micro";

await microInit({
  authHandler(token) {
    if (token) localStorage.setItem("token", token);
  },
  hideHeaderCssSelector: ["#app .app-header"],
  onActivated() {
    // 恢复轮询，并重新计算图表、地图等尺寸
  },
  onDeactivated() {
    // 暂停轮询、动画等后台任务
  },
});

| 参数 | 说明 | | --- | --- | | authHandler | 接收主应用传入的 token，支持异步函数 | | hideHeaderCssSelector | 微应用模式下隐藏的 CSS 选择器，可传字符串或数组 | | onActivated | iframe 被激活时调用，支持异步函数 | | onDeactivated | iframe 被隐藏时调用，支持异步函数 |

常用 API

import {
  createAppUrl,
  getApp,
  getApps,
  isMicro,
  isParent,
  reloadApp,
  startApp,
  stopApp,
} from "@xingtukeji/micro";

| API | 说明 | | --- | --- | | getApp(name) / getApps() | 获取已注册应用 | | startApp(name, options?) | 挂载并激活应用 | | stopApp(name) | 销毁应用 iframe | | reloadApp(name, isGoHome?) | 刷新应用；isGoHome 为 true 时回到配置的入口地址 | | createAppUrl(targetUrl, appName?) | 生成由主应用加载指定子应用页面的 URL | | isMicro() / isParent() | 判断当前运行环境 |

路由同步与新标签页

sync 开启时，子应用路由会写入主应用查询参数 __XT_MICRO_<应用名>。需要在新标签页中仍由主应用加载子页面时，可使用：

const url = createAppUrl("/orders/123?tab=detail#section", "order-app");
window.open(url, "_blank");

手工拼接时，子应用地址必须经过 encodeURIComponent：

const childUrl = encodeURIComponent("http://localhost:5173/page?tab=1#/detail");
const url = `${location.origin}/console/?__XT_MICRO_order-app=${childUrl}#/micro/order-app`;

调试与运行时信息

window.micro_api.debug(true); // 开启调试日志
window.micro_api.debug(false); // 关闭调试日志

window.__XT_MICRO_VERSION; // 当前框架版本
window.__XT_MICRO_APP; // 当前微应用信息及主应用 location