# micro-app-front-end **Repository Path**: echo-52hz/micro-app-front-end ## Basic Information - **Project Name**: micro-app-front-end - **Description**: 基于 micro-app（https://jd-opensource.github.io/micro-app/）框架构建企业级微前端模板 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2026-02-01 - **Last Updated**: 2026-02-09 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # micro-app 企业级微前端模板基于京东 **micro-app** 框架的企业级微前端项目模板，提供完整的主子应用通信、路由同步、多环境配置等核心功能。 ## 项目概述本项目采用简洁的项目结构，包含 1 个主应用和 3 个子应用，充分利用 micro-app 的原生路由模式和内置通信机制，提供开箱即用的微前端解决方案。 ### 技术栈 - **微前端框架**: @micro-zoe/micro-app (基于 WebComponent) - **前端框架**: Vue 3 + TypeScript - **构建工具**: Vite - **路由**: Vue Router 4 (createWebHistory + native 模式) - **包管理器**: pnpm ## 项目结构 ``` micro-app/ ├── main-app/ # 主应用（基座应用） │ ├── src/ │ │ ├── components/ # 组件目录 │ │ ├── config/ # 配置文件（子应用配置） │ │ ├── router/ # 路由配置 │ │ ├── views/ # 页面组件 │ │ ├── types/ # TypeScript 类型定义 │ │ ├── composables/ # 组合式函数 │ │ ├── App.vue # 根组件 │ │ └── main.ts # 入口文件 │ ├── .env.development # 开发环境配置 │ ├── .env.production # 生产环境配置 │ ├── vite.config.ts # Vite 配置 │ └── package.json │ ├── sub-app-1/ # 子应用 1 │ ├── src/ │ │ ├── router/ # 路由配置 │ │ ├── views/ # 页面组件 │ │ ├── utils/ # 工具函数（环境检测） │ │ ├── composables/ # 组合式函数（数据通信） │ │ ├── App.vue # 根组件 │ │ └── main.ts # 入口文件（支持独立运行） │ ├── .env.development # 开发环境配置 │ ├── .env.production # 生产环境配置 │ ├── vite.config.ts # Vite 配置 │ └── package.json │ ├── sub-app-2/ # 子应用 2（结构同 sub-app-1） ├── sub-app-3/ # 子应用 3（结构同 sub-app-1） ├── package.json # 根目录配置（一键启动脚本） └── README.md # 项目说明文档 ``` ## 快速开始 ### 环境要求 - Node.js >= 18.0.0 - pnpm >= 8.0.0 ### 安装依赖在项目根目录执行： ```bash # 安装根目录依赖 pnpm install # 安装所有应用的依赖 pnpm run install:all ``` ### 启动项目 #### 一键启动所有应用（推荐） ```bash pnpm run dev ``` 这将同时启动： - 主应用：http://localhost:5173 - 子应用 1：http://localhost:3000 - 子应用 2：http://localhost:3001 - 子应用 3：http://localhost:3002 #### 单独启动某个应用 ```bash # 仅启动主应用 pnpm run dev:main # 仅启动子应用 1 pnpm run dev:sub1 # 仅启动子应用 2 pnpm run dev:sub2 # 仅启动子应用 3 pnpm run dev:sub3 ``` ### 构建项目 ```bash # 构建所有应用 pnpm run build # 单独构建某个应用 pnpm run build:main pnpm run build:sub1 pnpm run build:sub2 pnpm run build:sub3 ``` ### 预览构建结果 ```bash # 构建并预览所有应用 pnpm run preview ``` ## 核心功能 ### 1. 主子应用通信 micro-app 提供了内置的数据通信 API，无需额外配置： **主应用向子应用发送数据**： ```typescript // 通过 :data 属性传递初始数据 // 通过 setData 动态发送数据 microApp.setData('sub-app-1', { message: 'Hello' }) ``` **子应用接收主应用数据**： ```typescript // 获取数据 const data = window.microApp.getData(); // 监听数据变化 window.microApp.addDataListener((data) => { console.log("收到主应用数据:", data); }); ``` **子应用向主应用发送数据**： ```typescript window.microApp.dispatch({ type: "event", payload: "data" }); ``` **主应用接收子应用数据**： ```typescript microApp.addDataListener("sub-app-1", (data) => { console.log("收到子应用数据:", data); }); ``` ### 2. 路由同步 micro-app 使用原生路由模式，自动处理路由同步： **主应用配置**： ```typescript // 配置子应用路由 { path: '/sub-app-1/:subpath*', component: SubApp1View } // 使用 native 模式 ``` **子应用配置**： ```typescript // 使用 createWebHistory（与独立运行一致） const router = createRouter({ history: createWebHistory(window.__MICRO_APP_BASE_ROUTE__ || "/"), routes, }); ``` ### 3. 跨应用导航子应用可以通过数据通信请求主应用进行跨应用导航： ```typescript // 子应用发送导航请求 window.microApp.dispatch({ type: "navigate", appName: "sub-app-2", path: "/about", }); // 主应用监听并处理 microApp.addDataListener((data) => { if (data.type === "navigate") { router.push(`/${data.appName}${data.path}`); } }); ``` ### 4. 环境配置项目支持多环境配置，通过环境变量灵活控制： **开发环境** (`.env.development`)： ```env VITE_DEPLOY_MODE=development VITE_SUB_APP_1_ENTRY=//localhost:3000 VITE_SUB_APP_2_ENTRY=//localhost:3001 VITE_SUB_APP_3_ENTRY=//localhost:3002 ``` **生产环境** (`.env.production`)： ```env VITE_DEPLOY_MODE=same-origin # 或跨域部署 # VITE_DEPLOY_MODE=cross-origin # VITE_SUB_APP_1_ENTRY=//sub1.example.com ``` ### 5. 子应用独立运行所有子应用都支持独立运行，便于开发调试： ```typescript // 环境检测 function isMicroAppEnvironment() { return window.__MICRO_APP_ENVIRONMENT__; } // 独立运行时直接挂载 if (!isMicroAppEnvironment()) { render(); } // 微前端环境导出生命周期函数 window.mount = () => render(); window.unmount = () => app.unmount(); ``` ## 可用脚本 | 脚本 | 说明 | | ------------------------- | ---------------------------- | | `pnpm run install:all` | 安装所有应用的依赖 | | `pnpm run dev` | 一键启动所有应用（开发模式） | | `pnpm run dev:main` | 仅启动主应用 | | `pnpm run dev:sub1/2/3` | 仅启动指定子应用 | | `pnpm run build` | 构建所有应用 | | `pnpm run build:main` | 仅构建主应用 | | `pnpm run build:sub1/2/3` | 仅构建指定子应用 | | `pnpm run preview` | 构建并预览所有应用 | ## 开发指南 ### 添加新的子应用 1. 复制现有子应用目录（如 `sub-app-1`） 2. 修改 `package.json` 中的项目名称 3. 修改 `vite.config.ts` 中的端口号 4. 在主应用的 `src/config/microApps.ts` 中添加配置 5. 在主应用的路由中添加对应路由 6. 在根目录 `package.json` 中添加启动脚本 ### 调试技巧 1. **查看通信数据**：在浏览器控制台使用 `window.microApp.getData()` 查看数据 2. **查看子应用状态**：micro-app 会在控制台输出生命周期日志 3. **独立调试子应用**：直接访问子应用端口（如 http://localhost:3000） 4. **路由调试**：检查 `window.__MICRO_APP_BASE_ROUTE__` 确认基础路由 ## 常见问题 ### 1. 子应用加载失败 **原因**： - 子应用未启动 - 端口配置错误 - CORS 配置问题 **解决方案**： - 确保子应用已启动 - 检查 `vite.config.ts` 中的端口配置 - 检查 Vite 的 CORS 配置 ### 2. 路由不同步 **原因**： - 未配置 `router-mode="native"` - 子应用使用了错误的路由模式 **解决方案**： - 确保主应用使用 `` - 确保子应用使用 `createWebHistory` ### 3. 样式冲突 **原因**： - 全局样式污染 **解决方案**： - micro-app 默认提供样式隔离 - 使用 scoped 样式或 CSS Modules - 避免使用全局样式选择器 ### 4. 通信数据未接收 **原因**： - 监听器未正确注册 - 数据发送时机错误 **解决方案**： - 确保在子应用挂载后注册监听器 - 使用 `autoTrigger: true` 自动触发初始数据 ## 部署指南 ### 同域部署所有应用部署在同一域名下： ``` https://example.com/ # 主应用 https://example.com/sub-app-1 # 子应用 1 https://example.com/sub-app-2 # 子应用 2 https://example.com/sub-app-3 # 子应用 3 ``` ### 跨域部署子应用部署在不同域名： ``` https://main.example.com/ # 主应用 https://sub1.example.com/ # 子应用 1 https://sub2.example.com/ # 子应用 2 https://sub3.example.com/ # 子应用 3 ``` 需要配置 CORS 头： ```nginx add_header Access-Control-Allow-Origin *; add_header Access-Control-Allow-Methods 'GET, POST, OPTIONS'; ``` ## 相关文档 ### 项目文档 - [踩坑记录](./docs/TROUBLESHOOTING.md) - 实现过程中遇到的问题和解决方案 - [实现过程记录](./docs/IMPLEMENTATION_LOG.md) - 完整的实现过程和技术决策 ### 官方文档 - [micro-app 官方文档](https://micro-zoe.github.io/micro-app/) - [Vue 3 文档](https://cn.vuejs.org/) - [Vite 文档](https://cn.vitejs.dev/) - [Vue Router 文档](https://router.vuejs.org/zh/) ## 许可证 MIT ## 贡献欢迎提交 Issue 和 Pull Request！