@kayak-sj/micro-app

PC 管理台微前端插件，基于 wujie-vue3 实现主子应用嵌套与通信。

对应旧工程 @kayak/kayak-plugin-micro-app（Vue 2 + wujie-vue2）。

定位

| 该放 | 不该放 | | ------------------------------ | --------------------------------- | | 主子应用嵌套、通信、保活 | 业务页面、CMS 系统管理页 | | wujie 配置、生命周期、polyfill | 业务 API、权限 store | | KayakMicroApp 宿主组件 | 通用 UI 组件（→ @kayak-sj/design） |

详见 包职责约定。

技术栈

• Vue 3 + TypeScript
• wujie-vue3
• wujie-polyfill

目录结构

micro-app/
├── README.md
├── package.json
└── src/
    ├── index.ts                 # 统一导出
    ├── install.ts               # setupMicroApp 安装入口
    ├── types.ts                 # 类型定义
    ├── injection.ts             # tagsView 可选注入
    ├── config/
    │   ├── appsConfig.ts        # 子应用配置仓库 AppsConfig
    │   └── appDefaultConfig.ts  # 默认配置与扩展字段定义
    ├── constants/
    │   └── mountedMicroApps.ts  # 全局首屏挂载记录（跨实例共享）
    ├── composables/
    │   ├── useMicroAppConfig.ts         # 子应用配置与 URL 派生
    │   ├── useMicroAppSkeleton.ts       # 骨架屏 / 加载状态
    │   ├── useMicroAppKeepAlive.ts      # keep-alive 适配
    │   └── useMicroAppRouteHandlers.ts  # 路由重置 / 刷新
    ├── components/
    │   ├── MicroAppHost.vue     # 宿主组件（导出为 KayakMicroApp）
    │   └── MicroAppSkeleton.vue # 加载骨架屏
    └── utils/
        ├── setupSubApp.ts       # 注册子应用到 wujie
        ├── bus.ts               # KayakMicroBus / destroyMicroApp
        ├── runtime.ts           # isPoweredByWujie / getWujieProps
        ├── plugins.ts           # wujie 兼容插件
        ├── lifecycles.ts        # wujie 生命周期
        ├── customDegrade.ts     # iframe 降级模式
        └── recursionFilter.ts   # 路由树过滤

快速开始

1. 配置子应用

在业务应用 kayak.config.ts 中声明：

export const appConfig = {
  systemId: 'rights',
  isMainApp: true,
  appMode: ['microApp', 'normal'] as const,
  microApps: [
    {
      systemId: 'member',
      url: 'http://localhost:5174/',
      preload: true,
      alive: true
    }
  ]
}

2. 安装（通常由 cms-base 间接调用）

// main.ts
import { setupCmsBase } from '@kayak-sj/cms-base'

setupCmsBase({
  app,
  router,
  pinia,
  systemId: appConfig.systemId,
  isMainApp: appConfig.isMainApp,
  appMode: [...appConfig.appMode],
  microApps: appConfig.microApps
})

也可直接调用：

import { setupMicroApp } from '@kayak-sj/micro-app'

setupMicroApp({
  app,
  apps: appConfig.microApps,
  isMainApp: appConfig.isMainApp,
  appMode: [...appConfig.appMode]
})

3. 页面中使用宿主组件

<script setup lang="ts">
import { ref } from 'vue'
import { onBeforeRouteEnter, onBeforeRouteLeave } from 'vue-router'
import { KayakMicroApp } from '@kayak-sj/micro-app'

const microAppRef = ref<InstanceType<typeof KayakMicroApp>>()

const hostProps = {
  token: 'xxx',
  userInfo: {},
  dynamicRoutes: []
}

onBeforeRouteLeave((to, from, next) => {
  microAppRef.value?.handleResetMicroRoute(to, from)
  next()
})

onBeforeRouteEnter((_to, _from, next) => {
  next(() => {
    microAppRef.value?.handleRefreshMicroRoute()
  })
})
</script>

<template>
  <KayakMicroApp ref="microAppRef" system-id="member" :props="hostProps" />
</template>

主要 API

| 导出 | 说明 | 旧工程对应 | | ------------------------- | ----------------------- | ----------------------------- | | setupMicroApp | 注册 wujie 与子应用配置 | MicroApp.install | | KayakMicroApp | 子应用宿主组件 | KayakMicroApp | | KayakMicroBus | 主子应用事件总线 | KayakMicroBus | | destroyMicroApp | 销毁子应用实例 | destroyMicroApp | | setupSubApp | 批量注册子应用 | setupSubApp | | AppsConfig | 子应用配置仓库 | AppsConfig | | isPoweredByWujie | 是否在子应用沙箱内 | window.__POWERED_BY_WUJIE__ | | getWujieProps | 获取主应用透传 props | window.$wujie.props | | MICRO_APP_TAGS_VIEW_KEY | 页签刷新注入 Key | vuex tagsView |

主子应用通信事件

| 事件名 | 触发时机 | | ------------------------------- | --------------------------------- | | on-micro-route-{systemId} | keep-alive 激活后、同子应用内宿主路由变化时同步子应用路由 | | on-reset-micro-route-{name} | 离开 noCache 页面时重置子应用路由 | | on-refresh-micro-route-{name} | 页签刷新时通知子应用更新视图 |

KayakMicroApp Props

| Prop | 类型 | 说明 | | -------------------- | ------------------------- | --------------------------------- | | systemId | string | 子应用系统 ID | | singleAppConfig | MicroAppDefinition | 单应用模式配置（覆盖 AppsConfig） | | subPathToComponent | string | 组件模式下直接指定子应用 URL | | props | Record<string, unknown> | 透传子应用参数（旧工程写法） | | hostProps | Record<string, unknown> | 透传子应用参数（新写法） | | skeletonDisabled | boolean | 是否关闭骨架屏 |

页签刷新集成（可选）

handleRefreshMicroRoute 依赖页签状态，由 @kayak-sj/cms-base 的 tagsView 模块 provide：

import { MICRO_APP_TAGS_VIEW_KEY } from '@kayak-sj/micro-app'

app.provide(MICRO_APP_TAGS_VIEW_KEY, {
  isRefreshMicro: (appName) => tagsStore.isRefreshMicro[appName],
  closeRefreshMicroView: (appName) => tagsStore.closeRefreshMicroView(appName)
})

未注入时，仅根据 route.meta.noCache 判断是否刷新。

keep-alive 行为说明

1. deactivated：loading=true，v-if 隐藏 WujieVue 宿主，子应用实例由 wujie alive 保活
2. activated：loading=false 恢复宿主，已挂载子应用跳过骨架屏
3. mountedMicroApps：全局 Set 记录首屏挂载状态，避免 tab 切回时重复展示骨架屏

旧源码对照

本地同步 Vue2 旧源码用于升级参考：

# 在 monorepo 根目录执行
pnpm sync:legacy

同步后路径：legacy/kayak-plugin-micro-app/（已加入 .gitignore）

发版

当前为 workspace 内部包（private: true）。验证通过后可：

1. 移除 private: true
2. 发布到私服（对应旧 @kayak/kayak-plugin-micro-app 的 Vue3 版本）

相关包

| 包 | 关系 | | ----------------- | -------------------------------------- | | @kayak-sj/cms-base | 调用 setupMicroApp，提供微前端路由页 | | @kayak-sj/cms-base | 提供 http 适配、权限等运行时能力 | | @kayak-sj/design | UI 组件，与 micro-app 解耦 |