Garfish微前端框架中Vite子应用接入指南

前言

在现代前端开发中，微前端架构已经成为解决大型应用复杂性和团队协作问题的有效方案。Garfish作为一款优秀的微前端框架，提供了完整的子应用接入方案。本文将重点介绍如何使用Vite构建的子应用接入Garfish主应用的技术细节和注意事项。

Vite子应用的特殊性

Vite作为新一代前端构建工具，以其极快的启动速度和热更新能力受到开发者青睐。但当Vite应用作为子应用接入Garfish时，需要注意一些特殊配置：

1. 沙箱机制：Vite应用必须关闭沙箱才能正常运行
2. 路由处理：需要正确处理basename以保证路由正常工作
3. 构建配置：需要调整Vite配置以适应微前端环境

沙箱配置详解

为什么需要关闭沙箱？

Vite应用在开发模式下依赖ES模块的动态导入和HMR（热模块替换）功能，这些特性与Garfish的沙箱机制存在冲突。关闭沙箱可以确保Vite应用正常运行，但同时也带来了一些注意事项：

// 主应用中正确配置沙箱关闭
Garfish.run({
  apps: [
    {
      name: 'vite-sub-app',
      activeWhen: '/vite-app',
      sandbox: false // 仅关闭当前子应用的沙箱
    }
  ]
})

沙箱关闭后的注意事项

1. 全局污染风险：子应用的全局变量会泄漏到主应用环境
2. 样式隔离失效：需要自行处理CSS作用域问题
3. 卸载清理：必须确保子应用卸载时清理所有全局副作用

接入步骤详解

1. 安装桥接库

Garfish提供了官方桥接库来简化接入过程：

npm install @garfish/bridge-vue-v3 --save

桥接库的主要作用：

• 封装了子应用的生命周期管理
• 提供了默认的挂载/卸载行为
• 处理了props传递等常见问题

2. 导出Provider函数

import { vueBridge } from '@garfish/bridge-vue-v3';

export const provider = vueBridge({
  rootComponent: App,
  appOptions: ({ basename }) => ({
    el: '#app',
    render: () => h(App),
    router: createRouter({
      history: createWebHistory(basename),
      base: basename,
      routes
    })
  })
});

3. 路由basename处理

正确处理basename是微前端路由的关键：

function createRouterWithBasename(basename) {
  return createRouter({
    history: createWebHistory(basename),
    base: basename,
    routes: [...]
  });
}

basename的作用：

• 确保子应用路由在主应用上下文正确解析
• 支持子应用独立运行和嵌入主应用两种模式
• 避免路由冲突

Vite配置调整

Vite作为子应用需要特殊配置：

1. base路径：必须与主应用分配的子应用路径一致
2. 构建输出：需要配置合适的输出格式和文件名
3. 开发服务器：需要配置CORS和支持history API fallback

独立运行兼容

良好的微前端应用应该既能嵌入主应用，也能独立运行：

if (!window.__GARFISH__) {
  // 独立运行模式
  createApp(App)
    .use(createRouterWithBasename('/'))
    .mount('#app');
}

这种设计模式的好处：

• 便于开发和调试子应用
• 支持渐进式迁移
• 提高子应用的可测试性

总结

将Vite构建的子应用接入Garfish框架需要特别注意沙箱关闭、路由basename处理和构建配置调整等关键点。通过遵循本文的指导原则，开发者可以构建出既能独立运行又能完美嵌入主应用的高质量子应用模块。