@micro-app-adapter/vue3-webpack

Vue 3 + Webpack 项目的微前端生命周期适配器，帮助 Vue 3 子应用快速接入微前端框架。

功能特性

核心功能

| 功能模块 | 功能描述 | 关键API | |---------|---------|--------| | 生命周期管理 | 自动注册 mount/unmount 生命周期到 window 对象 | registerVueMicroApp | | 独立运行支持 | 非微前端环境下自动启动应用，无需修改代码 | 自动检测 __MICRO_APP_ENVIRONMENT__ | | 路由同步 | 主子应用路由双向同步，支持声明式和编程式导航 | MicroAppRouter, useMicroAppNavigate | | 数据通信 | 监听主应用下发的数据变化，支持路由事件监听 | MicroAppDataListener, useMicroAppDataListener | | 环境判断 | 检测微前端运行环境，获取基础路由等信息 | isMicroApp, getBasename | | TypeScript 支持 | 完整的类型定义，提供良好的开发体验 | 所有API均有类型定义 | | public-path 支持 | 动态设置 Webpack 公共路径，解决资源加载问题 | import '@micro-app-adapter/vue3-webpack/public-path' |

技术特点

| 特性 | 说明 | |-----|------| | 📦 双模块格式 | 同时输出 ESM 和 CJS 格式，兼容不同的模块系统 | | 🎯 组合式 API | 提供完整的 Composition API 支持，符合 Vue 3 最佳实践 | | 💪 TypeScript | 完整类型支持，提供优秀的IDE提示 | | 🧩 组件化 | 提供开箱即用的路由组件，简化开发流程 | | 📤 多入口 | 支持独立引入 public-path 和 route-sync 模块 | | 🔧 public-path | 提供动态公共路径配置，解决微前端资源加载问题 |

安装

pnpm add @micro-app-adapter/vue3-webpack

# 或
npm install @micro-app-adapter/vue3-webpack

# 或
yarn add @micro-app-adapter/vue3-webpack

版本要求

| 依赖包 | 版本要求 | 说明 | |-------|---------|------| | Vue | >=3.0.0 | 支持 Vue 3 组合式 API | | Vue-Router | >=4.0.0 | 可选，路由同步功能需要 |

Vue 3 版本兼容性详情

| Vue 版本 | 支持状态 | 说明 | |---------|---------|------| | Vue 3.5+ | ✅ 完整支持 | 推荐版本，最新特性 | | Vue 3.0-3.4 | ✅ 完整支持 | 稳定版本 |

Vue-Router 版本兼容性

| Vue-Router 版本 | 支持状态 | 说明 | |----------------|---------|------| | Vue-Router 4.x | ✅ 完整支持 | 与 Vue 3 配套使用 | | Vue-Router 3.x | ❌ 不支持 | 适用于 Vue 2，请使用 Vue 2 适配器 |

快速开始

1. 配置 public-path（重要）

在应用入口文件最顶部引入：

// main.ts
import '@micro-app-adapter/vue3-webpack/public-path';

// 其他导入...
import { createApp } from 'vue';
import App from './App.vue';

⚠️ 注意: public-path 必须在所有其他导入之前引入，以确保资源路径正确。

2. 注册生命周期

// main.ts
import '@micro-app-adapter/vue3-webpack/public-path';
import { createApp } from 'vue';
import App from './App.vue';
import router from './router';
import { registerVueMicroApp } from '@micro-app-adapter/vue3-webpack';

// 注册微前端生命周期
registerVueMicroApp(App, {
  appName: 'vue3-webpack-sub-app',
  router,           // 可选
  mountId: '#app'   // 可选，默认 '#app'
});

3. 路由同步方案

方案一：使用 MicroAppRouter 组件（推荐）

<!-- App.vue -->
<template>
  <MicroAppRouter
    :routes="routes"
    default-path="/home"
    :basename="basename"
    history-mode="hash"
  />
</template>

<script setup lang="ts">
import { MicroAppRouter, RouteConfig, getBasename } from '@micro-app-adapter/vue3-webpack';
import Home from './pages/Home.vue';
import About from './pages/About.vue';
import User from './pages/User.vue';

const basename = getBasename();

const routes: RouteConfig[] = [
  { path: '/home', component: Home },
  { path: '/about', component: About },
  { path: '/user', component: User },
];
</script>

方案二：使用 MicroAppRouteView + MicroAppDataListener

<!-- App.vue -->
<template>
  <div v-if="isMicroApp()">
    <MicroAppDataListener :on-route-change="handleRouteChange" />
    <MicroAppRouteView 
      :routes="routes" 
      default-path="/home"
      :fallback="NotFound"
    />
  </div>
  <div v-else>
    <!-- 独立运行时的路由 -->
    <router-view />
  </div>
</template>

<script setup lang="ts">
import { 
  isMicroApp, 
  MicroAppDataListener, 
  MicroAppRouteView,
  RouteConfig 
} from '@micro-app-adapter/vue3-webpack';
import NotFound from './pages/NotFound.vue';

const routes: RouteConfig[] = [
  { path: '/home', component: Home },
  { path: '/about', component: About },
];

const handleRouteChange = (data: { path: string; event?: string }) => {
  console.log('路由变化:', data.path, data.event);
};
</script>

方案三：手动路由同步（使用 Composition API）

<!-- App.vue -->
<template>
  <div>
    <MicroAppDataListener />
    <component :is="currentComponent" />
  </div>
</template>

<script setup lang="ts">
import { computed, watch } from 'vue';
import { 
  isMicroApp, 
  useMicroAppRouteSync, 
  useMicroAppNavigate,
  MicroAppDataListener 
} from '@micro-app-adapter/vue3-webpack';

const { ready, targetPath } = useMicroAppRouteSync();
const { navigate } = useMicroAppNavigate();

// 根据路径动态渲染组件
const currentComponent = computed(() => {
  if (!ready.value) return null;
  return getComponentByPath(targetPath.value);
});

// 监听路由变化
watch(targetPath, (newPath) => {
  console.log('目标路径:', newPath);
});
</script>

API 文档

registerVueMicroApp

注册 Vue 应用的微前端生命周期。

function registerVueMicroApp(
  AppComponent: Component,
  options: RegisterVueMicroAppOptions
): void;

interface RegisterVueMicroAppOptions {
  appName: string;      // 子应用名称
  router?: Router;      // Vue Router 实例（可选）
  mountId?: string;     // 挂载容器选择器，默认 '#app'
}

使用示例：

import { createApp } from 'vue';
import { createRouter, createWebHistory } from 'vue-router';
import App from './App.vue';
import { registerVueMicroApp } from '@micro-app-adapter/vue3-webpack';

const router = createRouter({
  history: createWebHistory(),
  routes: [
    { path: '/home', component: Home },
    { path: '/about', component: About },
  ]
});

registerVueMicroApp(App, {
  appName: 'vue3-sub-app',
  router,
  mountId: '#app'
});

public-path

动态设置 Webpack 公共路径。

// 在入口文件顶部引入
import '@micro-app-adapter/vue3-webpack/public-path';

工作原理：

if (window.__MICRO_APP_ENVIRONMENT__) {
  __webpack_public_path__ = window.__MICRO_APP_PUBLIC_PATH__ || '/';
}

isMicroApp

判断当前是否运行在微前端环境。

function isMicroApp(): boolean;

getBasename

获取微前端基础路由。

function getBasename(): string;

useMicroAppRouteSync

获取路由同步状态的 Hook。

function useMicroAppRouteSync(): UseMicroAppRouteSyncResult;

interface UseMicroAppRouteSyncResult {
  ready: Ref<boolean>;
  targetPath: Ref<string>;
}

useMicroAppNavigate

获取导航函数的 Hook。

function useMicroAppNavigate(): { navigate: (path: string) => void };

导航行为：

| 环境 | 行为 | |-----|------| | 微前端环境 | 更新状态 + 通知主应用 + 同步到全局数据 | | 独立运行 | 更新 hash 路由 |

useMicroAppDataListener

数据监听 Hook。

function useMicroAppDataListener(
  onRouteChange?: (data: { path: string; event?: string }) => void
): void;

MicroAppDataListener

数据监听组件。

interface MicroAppDataListenerProps {
  onRouteChange?: (data: { path: string; event?: string }) => void;
}

const MicroAppDataListener: Component;

事件类型：

| 事件 | 说明 | |-----|------| | beforeShow | 子应用即将显示 | | afterShow | 子应用已显示 | | undefined | 普通路由切换 |

MicroAppRouteView

路由视图组件。

interface MicroAppRouteViewProps {
  routes: RouteConfig[];
  defaultPath?: string;
  fallback?: Component;
}

interface RouteConfig {
  path: string;
  component: Component;
  children?: RouteConfig[];
}

MicroAppRouter

一体化路由组件。

interface MicroAppRouterProps {
  routes: RouteConfig[];
  defaultPath?: string;
  basename?: string;
  historyMode?: 'hash' | 'history';
  fallback?: Component;
}

模块导出

适配器提供三个入口：

主入口

import { 
  registerVueMicroApp,
  isMicroApp,
  getBasename,
  MicroAppRouter,
  useMicroAppRouteSync,
  // ...
} from '@micro-app-adapter/vue3-webpack';

public-path 入口

import '@micro-app-adapter/vue3-webpack/public-path';

route-sync 入口

// 独立引入路由同步功能
import { 
  useMicroAppRouteSync,
  useMicroAppNavigate,
  MicroAppRouter
} from '@micro-app-adapter/vue3-webpack/route-sync';

类型导出

export type { 
  RegisterVueMicroAppOptions,
  MicroAppLifecycle,
  MicroAppRouteState,
  UseMicroAppRouteSyncResult,
  RouteConfig,
  MicroAppRouterProps
};

全局类型扩展

declare global {
  interface Window {
    __MICRO_APP_ENVIRONMENT__: boolean;
    __MICRO_APP_NAME__: string;
    __MICRO_APP_BASE_URL__: string;
    __MICRO_APP_PUBLIC_PATH__: string;
    [key: string]: any;
  }
  let __webpack_public_path__: string;
}

Webpack 配置建议

// webpack.config.js
module.exports = {
  output: {
    libraryTarget: 'umd',
    globalObject: 'window',
    publicPath: '/',
  },
  module: {
    rules: [
      {
        test: /\.vue$/,
        loader: 'vue-loader'
      }
    ]
  }
};

主应用配置示例

<micro-app 
  name="vue3-webpack-sub-app"
  url="http://localhost:8080"
  baseroute="/sub-app"
></micro-app>

完整示例

// main.ts
import '@micro-app-adapter/vue3-webpack/public-path';
import { registerVueMicroApp } from '@micro-app-adapter/vue3-webpack';
import App from './App.vue';
import router from './router';

registerVueMicroApp(App, {
  appName: 'vue3-webpack-sub-app',
  router,
  mountId: '#app'
});

<!-- App.vue -->
<template>
  <MicroAppRouter
    :routes="routes"
    default-path="/home"
    :basename="basename"
  />
</template>

<script setup lang="ts">
import { MicroAppRouter, RouteConfig, getBasename } from '@micro-app-adapter/vue3-webpack';
import Home from './pages/Home.vue';
import About from './pages/About.vue';

const basename = getBasename();

const routes: RouteConfig[] = [
  { path: '/home', component: Home },
  { path: '/about', component: About },
];
</script>

开发调试

# 安装依赖
pnpm install

# 开发模式
pnpm dev

# 构建
pnpm build

与 vue3-vite 版本的差异对比

| 特性 | vue3-webpack | vue3-vite | |-----|--------------|-----------| | 输出格式 | ESM + CJS | ESM | | public-path | 必须引入 | 不需要 | | route-sync 独立入口 | ✅ 支持 | ❌ 无 | | 构建工具 | Webpack | Vite | | 浏览器兼容性 | 更广泛 | 现代浏览器 | | 开发体验 | 生态更成熟 | 热更新更快 | | 适用场景 | 旧项目迁移、广泛兼容 | 新项目、现代浏览器 |

如何选择？

• 选择 vue3-webpack：需要广泛浏览器支持、从旧项目迁移、使用 Webpack 构建
• 选择 vue3-vite：新项目、使用 Vite 构建、目标用户使用现代浏览器

注意事项

1. public-path 必须最先引入: 确保在所有其他导入之前
2. Vue 版本: 要求 Vue 3.0+
3. 路由库: 可选使用 vue-router 4.0+，或使用内置路由组件
4. 构建输出: 同时输出 ESM 和 CJS 格式

常见问题

1. 资源加载 404？

确保正确引入了 public-path 模块，且在入口文件最顶部。

2. 样式加载异常？

检查 Webpack 的 publicPath 配置，确保与微前端环境兼容。

3. 路由不同步？

检查主应用是否正确下发了路由数据，子应用是否正确使用了路由同步组件。

License

MIT