GitHub - ChenyCHENYU/Robot_Admin at micro-app

Robot Admin — 企业级微前端（MicroApp）架构模板

_{传统 SPA}
_{中小型项目首选}

_{Bun Workspaces}
_{多应用统一管理}

_{Module Federation}
_{运行时模块共享}

_{⬅ 当前分支}
_{大型系统、团队协作}

中文 | English

🎯 分支定位

micro-app 分支是一个完整的企业级微前端架构模板，基于 @micro-zoe/micro-app 实现，开箱即用。

你正在查看的是 micro-app 分支，这是 Robot Admin 多架构系列中的微前端版本。

特性	说明
定位	企业级微前端系统架构模板，可直接用于生产
核心框架	@micro-zoe/micro-app v1.0.0-rc.29（京东开源）
沙箱模式	iframe 沙箱（Vite 8 原生兼容，零配置）
集成演示	配套智慧物流子应用（独立项目 `robot-logistics`，端口 3003）
门户工作台	统一系统入口，多子应用切换管理
通信机制	`data` 绑定 + `PostMessage` + `setData` 全局广播
主题同步	主应用 Dark/Light 模式实时同步所有子应用
适用场景	大型平台、中台系统、多团队协作、遗留系统改造

与其他分支的关系

main（单体 SPA）
  ↕ 功能同步
dev（开发主线）
  ↓ 微前端改造
micro-app ← 你在这里

📊 多架构对照

Robot Admin 提供多种架构，按业务规模自由选择：

架构类型	适用场景	特点	分支	文档
🏠 单体架构	中小型项目、快速原型	简单直接、开箱即用	`main`	本项目主文档
📦 Monorepo	多应用统一管理	代码复用、统一工具链	`monorepo`	完整指南
🔗 模块联邦	微应用动态加载	运行时共享、版本隔离	`feature/module-federation`	使用指南
🧩 微前端 ←	大型应用、团队协作	技术栈无关、独立部署	`micro-app`	本文档

⚡ 快速开始

环境要求

工具	版本	说明
Node.js	`≥ 22.x`	运行时环境
Bun	`≥ 1.x`	包管理器（必须，不支持 npm/yarn/pnpm）

第一步：克隆 micro-app 分支

git clone -b micro-app https://github.com/ChenyCHENYU/Robot_Admin.git
cd Robot_Admin

第二步：安装主应用依赖

bun install

第三步：克隆子应用（独立项目）

# 回到父目录，克隆物流子应用
cd ..
git clone https://github.com/ChenyCHENYU/robot-logistics.git
cd robot-logistics
bun install

第四步：启动完整微前端环境（需开两个终端）

# 终端 1 — 启动主应用（端口 1988）
cd Robot_Admin
bun run dev

# 终端 2 — 启动子应用：智慧物流（端口 3003）
cd robot-logistics
bun run dev

访问 http://localhost:1988 → 点击「门户工作台」→ 选择「智慧物流管理系统」即可体验微前端集成效果。

常用命令

# 主应用
bun run dev           # 开发环境（端口 1988）
bun run build         # 生产构建
bun run build:test    # 测试环境构建
bun run build:staging # 预发布构建
bun run lint          # 代码检查
bun run format        # 代码格式化
bun run cz            # 规范化提交

# 子应用（独立项目 robot-logistics）
cd ../robot-logistics
bun run dev           # 开发（端口 3003）
bun run build         # 生产构建
bun run preview       # 本地预览

🏗️ 系统架构

总体拓扑

┌─────────────────────────────────────────────────────────────────┐
│                   Robot Admin（主应用 :1988）                    │
│                                                                 │
│  ┌────────────┐  ┌──────────────┐  ┌────────────────────────┐  │
│  │   Portal    │  │   C_Header   │  │   Micro-App Container  │  │
│  │ (门户工作台) │  │ (系统级导航) │  │   (微应用渲染容器)      │  │
│  └──────┬─────┘  └──────┬───────┘  └──────────┬─────────────┘  │
│         │               │                     │                │
│         └───────────────┴─────────────────────┘                │
│                     data 绑定 / PostMessage / setData           │
│                              ↓                                 │
├─────────────────────────────────────────────────────────────────┤
│                       子应用层（独立运行）                        │
│                                                                 │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐  │
│  │  智慧物流系统 │  │  智能仓储系统 │  │     更多业务系统...   │  │
│  │ (Vue3 :3003) │  │  (任意技术栈) │  │    (独立部署、运行)   │  │
│  └──────────────┘  └──────────────┘  └──────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

核心设计原则

原则	说明
零改造接入	子应用无需暴露生命周期钩子，micro-app 自动渲染
类组件开发	`<micro-app name="app" url="http://..." />` 像写 Vue 组件一样集成子应用
沙箱隔离	iframe 沙箱，JS/CSS 完全隔离，子应用互不影响
Keep-Alive	切换子应用保留运行状态，无需重新加载
主题同步	主应用颜色/暗黑模式通过 `data` 绑定实时同步
独立部署	主应用和每个子应用可独立部署、独立发版
渐进集成	现有系统无需重构即可接入，支持任意技术栈

应用启动流程

main.ts → setupMicroApp()       ← micro-app 框架初始化（早于 Vue 实例）
        → createApp(App)
        → setupStore()           ← Pinia + 持久化
        → setupRequestCore()     ← Axios 请求核心
        → setupLayoutSystem()    ← 布局系统
        → router.isReady()
        → app.mount('#app')

📂 目录结构

遵循 micro-app 官方社区最佳实践：主应用 / shared 契约层 + 子应用独立项目。

Robot_Admin/                 # 主应用项目
│
├── src/                    # 主应用（Robot Admin 系统本身）
├── shared/                 # ★ 微前端共享契约层（主子通信协议）
├── envs/                   # 环境变量（含 VITE_MICRO_*_URL 子应用地址）
├── docs/                   # 架构文档
│
├── vite.config.ts          # 主应用构建配置
├── tsconfig.json           # TypeScript 配置
├── vercel.json             # 主应用 Vercel 部署（SPA 重写 + 安全头 + 缓存策略）
└── package.json            # 主应用依赖（含 @micro-zoe/micro-app）

robot-logistics/             # ★ 子应用（独立项目，独立仓库）
└── → 见 robot-logistics/README.md

四层详解

`src/` — 主应用（对应官方 `main-app/`）

Robot Admin 项目根目录即主应用，src/ 包含全量业务代码。微前端相关模块：

文件 / 目录	职责
`src/config/microApps.ts`	★ 子应用注册表（地址由 env 注入）
`src/plugins/micro-app.ts`	★ `microApp.start()` 框架初始化
`src/views/portal/`	★ 门户工作台（三栏布局，系统聚合入口）
`src/views/micro-app/`	★ 微应用容器（`<micro-app>` 渲染）
`src/types/micro-app.d.ts`	Window 扩展 + 模块声明
`src/router/publicRouter.ts`	`/portal` + `/micro-app/:id` 路由
`src/components/global/C_Header/`	系统顶部导航（门户按钮 + 菜单抽屉）

`shared/` — 微前端共享契约层（对应官方 `shared/`）

主应用团队维护，所有子应用消费。通过 @shared/* 路径别名导入：

文件	内容
`shared/constants/index.ts`	12 种 PostMessage 消息类型 + 事件名 + 存储键
`shared/types/index.ts`	通信数据接口（MicroAppData / Payload 等）
`shared/utils/index.ts`	`createMessage()` / `parseMessage()` 工具

子应用 — 独立项目（对应官方 `sub-apps/`）

子应用是独立的 Git 仓库，与主应用平级部署。主应用通过 envs/.env.* 中的 VITE_MICRO_<APP>_URL 环境变量获取子应用地址：

子应用	技术栈	端口	说明
`robot-logistics`	Vue 3 + Vite + Naive	3003	智慧物流（运单/仓储/车辆/路线）

# envs/.env.development
VITE_MICRO_LOGISTICS_URL = http://localhost:3003

# envs/.env.production
VITE_MICRO_LOGISTICS_URL = https://logistics.example.com

`docs/` — 架构文档

项目架构分析、选型决策等补充文档。核心内容已整合到本 README 中。

🔗 集成方式

1. micro-app 初始化（`src/plugins/micro-app.ts`）

import microApp from '@micro-zoe/micro-app'

export function setupMicroApp() {
  microApp.start({
    'disable-memory-router': false, // 开启子应用路由记忆
    'disable-patch-request': false, // 开启请求拦截
  })
}

2. 子应用配置（`src/config/microApps.ts`）

// 地址由 envs/.env.* 中的 VITE_MICRO_<APP>_URL 注入，不再硬编码
export const MICRO_APPS: Record<string, MicroAppConfig> = {
  logistics: {
    id: 'logistics',
    name: '智慧物流管理系统',
    url: import.meta.env.VITE_MICRO_LOGISTICS_URL || 'http://localhost:3003',
    icon: '🚚',
    description: '物流运输、仓储管理、车辆调度',
  },
}

3. 微应用容器（`src/views/micro-app/index.vue`）

<micro-app
  :name="appId"
  :url="appUrl"
  :data="appData"
  iframe
  keep-alive
  @mounted="handleMounted"
  @error="handleError"
  @datachange="handleDataChange"
></micro-app>

4. 路由配置（`src/router/publicRouter.ts`）

{ path: '/micro-app/:id', component: MicroAppView, meta: { keepAlive: true } },
{ path: '/portal',        component: PortalView }

🖥️ 门户工作台

Portal（src/views/portal/）是整个微前端系统的统一入口，三栏式工作台布局：

┌──────────────────────────────────────────────────────────┐
│  C_Header（系统级导航栏）                                  │
├──────────────────────────────────────────────────────────┤
│  应用快捷栏（横向，显示所有已集成/待集成子应用）              │
├─────────────┬────────────────────────┬───────────────────┤
│  左栏        │  中栏（工作区）         │  右栏（快捷面板）   │
│  用户卡片    │  任务列表               │  系统公告          │
│  统计数据    │  数据概览               │  快捷操作          │
└─────────────┴────────────────────────┴───────────────────┘

✅ 系统卡片展示所有注册子应用（已集成 / 待集成状态标识）
✅ 点击卡片跳转 /micro-app/:id 加载对应子应用
✅ 工作台数据（任务/公告/统计）可对接后端 API

📡 数据通信

方式一：`data` 绑定（主 → 子，推荐）

const appData = computed(() => ({
  token: userStore.token,
  userInfo: userStore.userInfo,
  theme: themeStore.isDark ? 'dark' : 'light',
  primaryColor: themeStore.primaryColor,
}))

方式二：`@datachange` 事件（子 → 主）

// 主应用监听
const handleDataChange = (e: CustomEvent) => {
  const { type, payload } = e.detail.data
  if (type === 'NAVIGATE') router.push(payload.path)
  if (type === 'LOGOUT') userStore.logout()
  if (type === 'NOTIFY') message.info(payload.text)
}

// 子应用发送
window.microApp?.dispatch({ type: 'NAVIGATE', payload: { path: '/dashboard' } })

方式三：`setGlobalData` 全局广播（主 → 所有子）

// 主应用广播（适合主题变更）
microApp.setGlobalData({ theme: isDark ? 'dark' : 'light' })

// 子应用接收
window.microApp?.addGlobalDataListener((data: any) => applyTheme(data.theme))

通信场景速查

场景	推荐方式
向特定子应用传 token/用户信息	`data` 绑定
主题变更通知所有子应用	`setGlobalData`
子应用请求主应用跳转	`@datachange`
子应用触发退出登录	`@datachange`

💼 业务场景

当前集成的子应用

子应用	技术栈	端口	功能模块	状态
智慧物流管理系统	Vue 3 + Vite 8 + Naive UI	3003	运单管理、车辆调度、仓储、路线规划	✅ 已集成
智能仓储系统	—	3004	库存管理、出入库、盘点	⏳ 待集成
数据分析平台	—	3005	BI 报表、实时看板	⏳ 待集成

典型业务场景

场景 1：企业数字化平台 主应用统一认证+权限+门户，各业务系统（ERP/OA/CRM/WMS）独立接入，统一入口管理。

场景 2：遗留系统零成本改造 现有老旧系统（React/jQuery/Vue 2）无需重构，在门户直接注册地址即可接入，渐进式现代化。

场景 3：多团队独立协作 各团队独立维护子应用仓库，主应用负责集成和统一导航，独立发版互不干扰。

➕ 新增子应用

第 1 步：注册配置（`src/config/microApps.ts`）

warehouse: {
  id: 'warehouse',
  name: '智能仓储系统',
  dev: 'http://localhost:3004',
  prod: 'https://warehouse.example.com',
  icon: '🚚',
  description: '仓库管理、库存盘点、出入库',
},

第 2 步：添加门户入口（`src/views/portal/index.vue`）

{ id: 'warehouse', name: '智能仓储系统', icon: 'ri:database-2-line', color: '#18a058', integrated: true }

第 3 步：子应用配置 CORS（`vite.config.ts`）

server: {
  port: 3004,
  headers: { 'Access-Control-Allow-Origin': '*' },
}

第 4 步：配置 baseroute（history 模式）

history: createWebHistory(window.__MICRO_APP_BASE_ROUTE__ || '/')

无需改造子应用源码！ iframe 沙箱仅需确保跨域可访问。

子应用兼容性

技术栈	支持	说明
Vue 3 + Vite	✅	推荐
Vue 2	✅	零改造
React 18+	✅	零改造
Angular	✅	零改造
jQuery / 原生 HTML	✅	均可接入

🚀 部署方案

独立部署原则

主应用（Vercel/CDN）          子应用（独立服务器/CDN）
https://robotadmin.cn    +   https://logistics.example.com
              ↘               ↗
               用户浏览器（iframe 跨域加载）

主应用部署（Vercel，推荐）

git push origin micro-app   # 推送触发自动部署
# 或手动构建：bun run build → 上传 dist/

子应用 Nginx 配置

server {
  listen 3003;
  root /var/www/logistics/dist;
  location / { try_files $uri $uri/ /index.html; }
  add_header Access-Control-Allow-Origin "https://robotadmin.cn";
}

多环境自动切换

bun run build           # 使用 prod 地址
bun run build:test      # 使用 test 地址
bun run build:staging   # 使用 staging 地址

部署检查清单

子应用生产服务器已配置 Access-Control-Allow-Origin
envs/.env.production 中 VITE_MICRO_*_URL 已填写生产地址
主应用 SPA 重写规则已配置（vercel.json 已包含）

❓ 常见问题（FAQ）

问题	原因	解决方案
子应用静态资源 404	相对路径被主应用 URL 解析拦截	子应用 `vite.config.ts` 设置 `base` 为完整 URL
子应用 HMR 不生效	沙箱拦截 WebSocket	确保 `disable-patch-request: false`（已默认配置）
ESLint 报 `<micro-app>` 错误	`vue/component-name-in-template-casing` 规则	添加 `<!-- eslint-disable-next-line -->` 注释
子应用全局变量污染	with 沙箱对 `var` 声明无法拦截	使用 `iframe` 沙箱（已配置为默认）
子应用路由跳转不生效	iframe 沙箱隔离了 `history`	通过 PostMessage `MICRO_APP_NAVIGATE` 通知主应用跳转
子应用 Vue Devtools 无法调试	iframe 沙箱隔离了 devtools 注入	直接访问 `http://localhost:3003` 独立调试
微应用间样式冲突	多子应用同时渲染时全局样式互影响	iframe 沙箱天然隔离（无此问题）
子应用加载白屏	CORS / URL / 网络问题	检查：独立访问 → CORS 头 → 控制台错误 → `getMicroAppUrl()` 返回值

📚 深入阅读

文档	内容
micro-app 官方文档	API、沙箱配置、生命周期参考
robot-logistics 子应用	智慧物流子应用独立项目

micro-app 官方 API 速查

方法	说明
`microApp.start(options)`	启动微前端框架
`microApp.preFetch(apps)`	预加载子应用资源
`microApp.setData(appName, data)`	向子应用推送数据
`microApp.getData(appName)`	获取子应用数据
`microApp.setGlobalData(data)`	设置全局数据
`microApp.getGlobalData()`	获取全局数据

子应用环境变量	说明
`window.__MICRO_APP_ENVIRONMENT__`	是否在 micro-app 沙箱中
`window.__MICRO_APP_NAME__`	当前子应用 name
`window.__MICRO_APP_BASE_ROUTE__`	子应用 baseroute

🗺️ 演进路线

已实现（Phase 1 — 基础架构）

micro-app 启动 + iframe 沙箱
门户工作台（三栏布局）
微应用容器（PostMessage + 主题同步 + keep-alive）
子应用示例工程（logistics）
shared/ 契约层（类型 / 常量 / 工具）
环境变量驱动子应用地址
PostMessage origin 安全加固

Phase 2 — 通信增强 + 性能优化

任务	预期收益
`preFetch` 子应用预加载	首次切换提速 60%
增强错误边界（重试 + 降级）	子应用故障不影响主应用
`globalData` 全局数据广播	多子应用数据共享
`fiber` 异步渲染	大型子应用不阻塞
`globalAssets` 共享依赖 CDN	减少 30% 总包体积

Phase 3 — 治理能力

任务	预期收益
子应用动态注册 / 卸载	后端驱动，免部署
子应用健康检查	故障自动发现
多语言同步	主子应用语言统一
子应用权限 RBAC	按角色分配可见子应用

Phase 4 — 规模化

任务	预期收益
`shared/` 发布为 npm 包	跨仓库契约共享
子应用 CI/CD 模板	标准化发布流程
子应用动态注册（后端 API）	运营自主配置门户

✨ 技术栈

技术	版本	用途
@micro-zoe/micro-app	^1.0.0-rc.29	微前端框架（京东开源）
Vue	3.5.13	主应用框架
TypeScript	~5.8.0	类型安全
Vite	8.0.1	构建工具
Naive UI	2.41.0+	UI 组件库
Pinia	3.0.1	状态管理
Vue Router	4.5.0	路由系统
UnoCSS	66+	原子化 CSS
@robot-admin/naive-ui-components	0.6.10	51+ 业务组件库
Bun	≥1.x	包管理器（必须）

🤝 参与贡献

git clone -b micro-app https://github.com/yourusername/Robot_Admin.git
bun install
git checkout -b feat/your-feature
bun run cz
# 提 PR 到 micro-app 分支

贡献方向： 新子应用接入示例 · preFetch 预加载优化 · 错误边界增强 · shared/ 契约包 · 文档完善

详见 CONTRIBUTING.md

📄 许可证

🤖 Robot Admin micro-app — 让微前端架构从复杂回归简单

⭐ 给个 Star · 🌐 在线体验 · 🐛 提交 Issue

Name		Name	Last commit message	Last commit date
Latest commit History 725 Commits
.github		.github
.husky		.husky
.vscode		.vscode
docs		docs
envs		envs
lang		lang
public		public
scripts		scripts
shared		shared
src		src
tsconfig		tsconfig
.cz-config.js		.cz-config.js
.editorconfig		.editorconfig
.env.example		.env.example
.fileheader		.fileheader
.gitattributes		.gitattributes
.gitignore		.gitignore
.prettierrc.js		.prettierrc.js
.vercelignore		.vercelignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
README.md		README.md
README_EN.md		README_EN.md
bun.lock		bun.lock
commitlint.config.js		commitlint.config.js
cspell.json		cspell.json
eslint.config.ts		eslint.config.ts
index.html		index.html
package.json		package.json
tsconfig.json		tsconfig.json
unocss.config.ts		unocss.config.ts
vercel.json		vercel.json
vite.config.ts		vite.config.ts

Folders and files

Latest commit

History

Repository files navigation

🎯 分支定位

与其他分支的关系

📊 多架构对照

⚡ 快速开始

环境要求

第一步：克隆 micro-app 分支

第二步：安装主应用依赖

第三步：克隆子应用（独立项目）

第四步：启动完整微前端环境（需开两个终端）

常用命令

🏗️ 系统架构

总体拓扑

核心设计原则

应用启动流程

📂 目录结构

四层详解

src/ — 主应用（对应官方 main-app/）

shared/ — 微前端共享契约层（对应官方 shared/）

子应用 — 独立项目（对应官方 sub-apps/）

docs/ — 架构文档

🔗 集成方式

1. micro-app 初始化（src/plugins/micro-app.ts）

2. 子应用配置（src/config/microApps.ts）

3. 微应用容器（src/views/micro-app/index.vue）

4. 路由配置（src/router/publicRouter.ts）

🖥️ 门户工作台

📡 数据通信

方式一：data 绑定（主 → 子，推荐）

方式二：@datachange 事件（子 → 主）

方式三：setGlobalData 全局广播（主 → 所有子）

通信场景速查

💼 业务场景

当前集成的子应用

典型业务场景

➕ 新增子应用

第 1 步：注册配置（src/config/microApps.ts）

第 2 步：添加门户入口（src/views/portal/index.vue）

第 3 步：子应用配置 CORS（vite.config.ts）

第 4 步：配置 baseroute（history 模式）

子应用兼容性

🚀 部署方案

独立部署原则

主应用部署（Vercel，推荐）

子应用 Nginx 配置

多环境自动切换

部署检查清单

❓ 常见问题（FAQ）

📚 深入阅读

micro-app 官方 API 速查

🗺️ 演进路线

已实现（Phase 1 — 基础架构）

Phase 2 — 通信增强 + 性能优化

Phase 3 — 治理能力

Phase 4 — 规模化

✨ 技术栈

🤝 参与贡献

📄 许可证

About

Topics

Resources

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 35

Uh oh!

Contributors

Uh oh!

Languages

`src/` — 主应用（对应官方 `main-app/`）

`shared/` — 微前端共享契约层（对应官方 `shared/`）

子应用 — 独立项目（对应官方 `sub-apps/`）

`docs/` — 架构文档

1. micro-app 初始化（`src/plugins/micro-app.ts`）

2. 子应用配置（`src/config/microApps.ts`）

3. 微应用容器（`src/views/micro-app/index.vue`）

4. 路由配置（`src/router/publicRouter.ts`）

方式一：`data` 绑定（主 → 子，推荐）

方式二：`@datachange` 事件（子 → 主）

方式三：`setGlobalData` 全局广播（主 → 所有子）

第 1 步：注册配置（`src/config/microApps.ts`）

第 2 步：添加门户入口（`src/views/portal/index.vue`）

第 3 步：子应用配置 CORS（`vite.config.ts`）