# micro-app-web

**Repository Path**: ZY_RAN/micro-app-web

## Basic Information

- **Project Name**: micro-app-web
- **Description**: micro-app 微前端尝鲜
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-02-27
- **Last Updated**: 2026-03-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Micro App 微前端项目

基于 **micro-app** 的微前端架构解决方案，采用 pnpm Monorepo 管理，集成现代化开发工具链。

## 📋 项目概述

这是一个使用 **京东 micro-app** 方案构建的微前端项目，旨在解决大型前端应用的拆分、独立开发和团队协作问题。通过 micro-app 提供的 Web Components + 自定义元素技术，实现简单高效的微前端架构。

### ✨ 核心特性

- 🚀 **轻量级集成**: 基于 micro-app 的 Web Components 方案，无需复杂的模块联邦配置
- 📦 **Monorepo 管理**: 使用 pnpm workspace 统一管理多个子应用
- 🔧 **独立开发**: 各个微应用可以独立开发、构建和部署
- 🎯 **Vue 3 技术栈**: 所有应用统一使用 Vue 3 + TypeScript + Vite
- 🌐 **沙箱隔离**: 样式隔离、JS 沙箱，确保应用间互不干扰
- 🔄 **应用通信**: 完善的全局状态管理和应用间通信机制
- 📏 **统一规范**: ESLint + Prettier + Commitlint 保证代码质量

## 🛠 技术栈

### 核心技术
- **微前端框架**: [@micro-zoe/micro-app](https://github.com/Conditional-Web-Front/micro-app) (1.0.0-rc.29)
- **主框架**: Vue 3.4.37
- **语言**: TypeScript 5.4.2
- **构建工具**: Vite 5.4.1

### UI 与组件
- **UI 框架**: Element Plus 2.8.3
- **图标库**: @element-plus/icons-vue 2.3.2

### 状态管理与路由
- **状态管理**: Pinia 2.2.2
- **路由**: Vue Router 4.4.5

### 网络请求
- **HTTP 客户端**: Axios 1.7.7
- **Cookie 处理**: js-cookie 3.0.5

### 开发工具
- **包管理**: pnpm 10.30.3
- **代码检查**: ESLint 9.11.0 + @eslint/js
- **代码格式化**: Prettier 3.3.3
- **提交规范**: Commitlint 19.5.0 + Husky 8.0.0
- **Git Hooks**: lint-staged 15.5.2
- **Mock 服务**: vite-plugin-mock 3.0.2

### 其他工具
- **CSS 预处理**: Sass 1.80.6
- **拖拽排序**: Sortablejs 1.15.3
- **二维码**: qrcode 1.5.4
- **剪贴板**: vue-clipboard3 2.0.0
- **全屏**: screenfull 6.0.2
- **参数解析**: qs 6.13.0

## 📁 项目结构

```
module-federation/
├── apps/                           # 应用层目录
│   ├── base/                       # 主应用（基座）
│   │   ├── src/                    # 源码目录
│   │   │   ├── api/                # API 接口层
│   │   │   ├── common/             # 公共模块
│   │   │   │   ├── config/         # 配置文件
│   │   │   │   └── http/           # HTTP 请求封装
│   │   │   ├── components/         # 全局组件
│   │   │   │   ├── container-box/  # 容器组件
│   │   │   │   ├── dialog/         # 对话框组件
│   │   │   │   ├── search/         # 搜索组件
│   │   │   │   └── table/          # 表格组件
│   │   │   ├── directive/          # 自定义指令
│   │   │   ├── router/             # 路由配置
│   │   │   ├── stores/             # 状态管理
│   │   │   ├── theme/              # 主题样式
│   │   │   ├── types/              # TypeScript 类型定义
│   │   │   ├── utils/              # 工具函数
│   │   │   ├── views/              # 页面视图
│   │   │   │   ├── child01/        # 子应用 01 页面
│   │   │   │   ├── error/          # 错误页面
│   │   │   │   ├── home/           # 首页
│   │   │   │   ├── login/          # 登录页
│   │   │   │   ├── mine/           # 个人中心
│   │   │   │   └── table-dome/     # 表格局域网
│   │   │   ├── App.vue             # 根组件
│   │   │   └── main.ts             # 入口文件
│   │   ├── env/                    # 环境配置
│   │   ├── public/                 # 静态资源
│   │   ├── commitlint.config.js    # Commitlint 配置
│   │   ├── eslint.config.js        # ESLint 配置
│   │   ├── vite.config.ts          # Vite 配置
│   │   ├── tsconfig.json           # TypeScript 配置
│   │   └── package.json            # 依赖配置
│   │
│   ├── child01/                    # 子应用 01
│   │   ├── src/                    # 源码目录（结构同 base）
│   │   ├── env/                    # 环境配置
│   │   ├── public/                 # 静态资源
│   │   ├── vite.config.ts          # Vite 配置
│   │   ├── tsconfig.json           # TypeScript 配置
│   │   └── package.json            # 依赖配置
│   │
│   └── login-center/               # 登录中心（微应用）
│       ├── src/                    # 源码目录
│       │   ├── assets/             # 静态资源
│       │   │   ├── logo-mini.svg   # Logo 图标
│       │   │   ├── login-main.svg  # 登录主图
│       │   │   └── login-bg.svg    # 登录背景
│       │   ├── common/             # 公共模块
│       │   │   └── http/           # HTTP 请求封装
│       │   ├── directive/          # 自定义指令
│       │   ├── router/             # 路由配置
│       │   ├── stores/             # 状态管理
│       │   ├── theme/              # 主题样式
│       │   ├── utils/              # 工具函数
│       │   ├── views/              # 页面视图
│       │   │   ├── error/          # 错误页面
│       │   │   │   ├── 401.vue     # 401 页面
│       │   │   │   └── 404.vue     # 404 页面
│       │   │   └── login/          # 登录页面
│       │   │       ├── component/  # 登录子组件
│       │   │       │   ├── account.vue  # 账号登录
│       │   │       │   ├── mobile.vue   # 手机登录
│       │   │       │   └── scan.vue     # 扫码登录
│       │   │       └── index.vue        # 登录主页
│       │   ├── App.vue             # 根组件
│       │   └── main.ts             # 入口文件
│       ├── env/                    # 环境配置
│       ├── mock/                   # Mock 数据
│       │   ├── index.ts            # Mock 入口
│       │   └── login.ts            # 登录 Mock
│       ├── public/                 # 静态资源
│       ├── vite.config.ts          # Vite 配置
│       ├── tsconfig.json           # TypeScript 配置
│       ├── package.json            # 依赖配置
│       └── README.md               # 登录中心文档

├── packages/                       # 共享包
│   ├── shared/                     # 共享类型和常量
│   │   ├── src/
│   │   │   └── index.ts
│   │   ├── package.json
│   │   └── tsconfig.json
│   └── utils/                      # 共享工具函数
│       ├── src/
│       │   └── index.ts
│       ├── package.json
│       └── tsconfig.json

├── .husky/                         # Git Hooks 配置
│   ├── pre-commit                  # 提交前钩子
│   └── commit-msg                  # 提交信息验证
├── .gitignore                      # Git 忽略文件
├── .prettierrc.js                  # Prettier 配置
├── .eslintignore                   # ESLint 忽略文件
├── commitlint.config.js            # 根目录 Commitlint 配置
├── docker-compose.yml              # Docker Compose 配置
├── Dockerfile                      # Docker 镜像配置
├── nginx.conf                     # Nginx 配置
├── lerna.json                      # Lerna 配置
├── package.json                    # 根目录配置
├── pnpm-lock.yaml                  # 依赖锁定文件
├── pnpm-workspace.yaml             # pnpm 工作区配置
└── README.md                       # 项目文档
```

## 🚀 快速开始

### 环境准备

确保你的开发环境满足以下要求：

- **Node.js**: >= 22.12.0
- **pnpm**: >= 10.30.3
- **Git**: 最新版本

### 安装依赖

```bash
# 克隆项目
git clone <your-repo-url>
cd module-federation

# 安装根目录依赖
pnpm install
```

### 启动应用

#### 方式一：同时启动所有应用（推荐）

```bash
# 启动主应用和所有子应用
pnpm start
```

这将同时启动 `base`（主应用）、`child01`（子应用）和 `login-center`（登录中心）。

#### 方式二：单独启动某个应用

```bash
# 启动主应用（基座）
cd apps/base
pnpm dev

# 启动子应用
cd apps/child01
pnpm dev

# 启动登录中心
cd apps/login-center
pnpm dev
```

### 访问地址

- **主应用 (base)**: http://localhost:8000
- **子应用 (child01)**: http://localhost:8889
- **登录中心 (login-center)**: http://localhost:8890

## 🏗 微前端架构

### 技术选型：micro-app

本项目采用 **京东 micro-app** 方案，相比其他微前端方案有以下优势：

| 特性 | micro-app | qiankun | iframe |
|------|-----------|---------|--------|
| 上手难度 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
| 侵入性 | 低 | 高 | 无 |
| 性能 | 优秀 | 良好 | 一般 |
| 样式隔离 | ✅ | ✅ | ✅ |
| JS 沙箱 | ✅ | ✅ | ✅ |
| 通信机制 | 完善 | 完善 | 受限 |

### 主应用配置

在主应用 (`apps/base`) 中初始化 micro-app：

```typescript
// src/main.ts
import { createApp } from 'vue'
import microApp from '@micro-zoe/micro-app'
import App from './App.vue'

const app = createApp(App)

// 启动 micro-app
microApp.start({
  "keep-alive": true
})

app.mount('#app')
```

在页面中嵌入子应用：

```vue
<!-- src/views/child01/index.vue -->
<template>
  <div class="child-page">
    <micro-app
     name="child01"
      url="http://localhost:8889/"
      :data="{ path: $route.params.pathMatch }"
    ></micro-app>
  </div>
</template>
```

### 子应用配置

子应用 (`apps/child01`) 需要适配 micro-app 环境：

```typescript
// src/main.ts
import { createApp } from 'vue'
import App from './App.vue'
import router from './router'

const app = createApp(App)
app.use(router)
app.mount('#vite-app')
```

### 环境变量配置

#### 主应用 (.env.development)

```bash
# 子应用访问地址
VITE_MICRO_APP_CHILD01_URL=http://localhost:8889/
```

#### 子应用 (vite.config.ts)

```typescript
export default defineConfig({
  base: '/',
  server: {
    port:8889,
   cors: true, // 必须启用 CORS
   host: '0.0.0.0',
  },
})
```

## 🔧 开发指南

### 项目配置

#### Vite 配置示例（主应用）

```typescript
// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import { fileURLToPath } from 'node:url'

export default defineConfig({
  base: '/main-vite/',
  plugins: [
    vue({
      template: {
       compilerOptions: {
          isCustomElement: tag => /^micro-app/.test(tag)
        }
      }
    })
  ],
  resolve: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url))
    }
  },
  server: {
   host: '0.0.0.0',
    port:8000,
    open: true
  }
})
```

#### TypeScript 配置

```json
{
  "compilerOptions": {
    "target": "ES2020",
    "useDefineForClassFields": true,
    "module": "ESNext",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "skipLibCheck": true,
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,
    "jsx": "preserve",
    "strict": true,
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}
```

### 代码规范

#### Git 提交规范

项目使用 **Conventional Commits** 规范，通过 Commitlint + Husky 自动验证：

```bash
# 正确的提交示例
git commit -m "feat(base): 添加用户登录功能"
git commit -m "fix(child01): 修复日期选择器时区问题"
git commit -m "docs(readme): 更新安装说明"

# 错误的提交（会被拒绝）
git commit -m "update code"      # ❌ 格式不规范
git commit -m "fixed bug"        # ❌ 时态错误
```

**Type 类型说明：**

| Type | 说明 | 示例 |
|------|------|------|
| `feat` | 新功能 | `feat: add export to Excel` |
| `fix` | 修复 Bug | `fix: correct date format` |
| `docs` | 文档更新 | `docs: update API docs` |
| `style` | 代码格式 | `style: format with prettier` |
| `refactor` | 重构 | `refactor: optimize render function` |
| `perf` | 性能优化 | `perf: reduce bundle size` |
| `test` | 测试相关 | `test: add unit tests` |
| `chore` | 构建/工具 | `chore: update dependencies` |

**常用 Scope 范围：**

| Scope | 说明 | 适用场景 |
|-------|------|----------|
| `base` | 主应用 | 影响基座应用的更改 |
| `child01` | 子应用 01 | 影响第一个子应用的更改 |
| `login-center` | 登录中心 | 影响登录中心的更改 |
| `router` | 路由 | 路由配置、路由守卫等 |
| `store` | 状态管理 | Pinia store 相关更改 |
| `component` | 组件 | 通用组件库的更改 |
| `api` | 接口 | API 接口层更改 |
| `utils` | 工具函数 | 工具类函数更改 |
| `theme` | 主题样式 | 主题、样式相关更改 |
| `deps` | 依赖 | 依赖包更新 |
| `readme` | 文档 | README 等文档更新 |

#### 代码风格

- **命名规范**: 
  - 变量/函数：camelCase（小驼峰）
  - 组件名：PascalCase（大驼峰）
  - 常量：UPPER_SNAKE_CASE
- **文件格式**: 
  - Vue 组件：`.vue`
  - TypeScript：`.ts`
  - 类型定义：`.d.ts`
- **引号**: 单引号 `'`
- **分号**: 必须使用分号 `;`
- **缩进**: 2 个空格

### 应用间通信

#### 主应用向子应用传递数据

```vue
<!-- 主应用 -->
<template>
  <micro-app
   name="child01"
    url="http://localhost:8889/"
    :data="{ userInfo: currentUser, theme: 'dark' }"
  ></micro-app>
</template>
```

```typescript
// 子应用接收数据
import microApp from '@micro-zoe/micro-app'

microApp.addListener((data) => {
  console.log('来自主应用的数据:', data)
  // data.userInfo, data.theme
})
```

#### 子应用向主应用发送消息

```typescript
// 子应用
microApp.dispatch({ type: 'user-login', payload: userData })
```

```typescript
// 主应用
microApp.setData('child01', { loggedIn: true })
```

## 📦 包管理策略

### 工作区结构

采用 pnpm workspace 管理模式：

```yaml
# pnpm-workspace.yaml
packages:
  - 'apps/*'
  - 'packages/*'
```

### 依赖管理

```bash
# 添加依赖到根目录
pnpm add -w some-package

# 添加依赖到特定应用
pnpm add axios --filter base
pnpm add element-plus --filter child01

# 添加开发依赖
pnpm add -D vite --filter base

# 移除依赖
pnpm remove some-package --filter base
```

### 脚本命令

```bash
# 根目录脚本
pnpm setup          # 安装所有依赖
pnpm start          # 启动所有应用
pnpm build          # 构建所有应用

# 单个应用脚本
cd apps/base
pnpm dev            # 启动开发服务器
pnpm build          # 构建生产版本
pnpm preview        # 预览构建结果
pnpm commit         # 使用 commitizen 提交
```

## 🎯 功能模块

### 已实现功能

#### ✅ 基础架构
- [x] Monorepo 项目结构
- [x] pnpm workspace 配置
- [x] micro-app 微前端集成
- [x] Vue 3 + TypeScript + Vite
- [x] Element Plus 组件库

#### ✅ 核心功能
- [x] 路由系统（Vue Router）
- [x] 状态管理（Pinia）
- [x] HTTP 请求封装（Axios）
- [x] 权限控制
- [x] 用户登录/登出
- [x] Mock 服务（支持生产环境）

#### ✅ 组件库
- [x] ContainerBox 容器组件
- [x] Dialog 对话框组件
- [x] Search 搜索组件
- [x] Table 表格组件

#### ✅ 开发工具
- [x] ESLint 代码检查
- [x] Prettier 代码格式化
- [x] Commitlint 提交规范
- [x] Husky Git Hooks
- [x] lint-staged 暂存文件检查

#### ✅ 主题系统
- [x] 暗黑模式
- [x] 主题切换
- [x] 自定义主题配置

### 🚧 开发中

- [ ] 更多业务组件
- [ ] 国际化支持
- [ ] 单元测试
- [ ] E2E 测试
- [ ] 性能优化

### 🔮 规划中

- [ ] 更多子应用接入
- [ ] 共享组件库建设
- [ ] 微前端监控体系
- [ ] 自动化部署流程

## 🐳 Docker 部署

### 构建镜像

```bash
# 构建所有应用的 Docker 镜像
docker-compose build
```

### Docker Compose

```bash
# 启动所有服务
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down
```

### Nginx 配置

项目包含完整的 Nginx 配置 (`nginx.conf`)，支持：

- **主应用** `/main-vite/` → 基座应用
- **子应用** `/app-vite/` → 子应用 01
- **登录中心** `/login-center/` → 登录服务
- **Mock 服务** `/mock/` → Mock API
- **Gzip 压缩**：优化加载性能
- **静态资源缓存**：30 天长期缓存
- **HTML 不缓存**：确保最新代码
- **跨域支持**：CORS  headers

### 部署架构

所有应用（主应用、子应用、登录中心）部署在同一域名下，通过路径区分：

```
http://localhost:8050/
├── /main-vite/      → 主应用 (base)
├── /app-vite/       → 子应用 (child01)
├── /login-center/   → 登录中心
└── /mock/api/       → Mock API
```

**优势：**
- ✅ 同域部署天然避免跨域问题
- ✅ Cookie 自动共享，不受第三方 Cookie 策略影响
- ✅ 无需复杂的 SSO 或跨域通信机制
- ✅ 部署简单，安全性高，维护成本低

## 📊 性能优化

### 代码分割

```typescript
// 路由懒加载
const routes = [
  {
   path: '/home',
   component: () => import('@/views/home/index.vue')
  }
]
```

### 按需引入

```typescript
// 按需引入 Element Plus 组件
import { ElButton, ElTable } from 'element-plus'
app.use(ElButton).use(ElTable)
```

### 构建优化

```typescript
// vite.config.ts
export default defineConfig({
  build: {
    minify: false,
    target: ["chrome89", "edge89", "firefox89", "safari15"],
    cssCodeSplit: false,
    rollupOptions: {
      output: {
        format: 'umd'
      }
    }
  }
})
```

## 🤝 贡献指南

### 分支策略

- `main`: 生产环境分支（稳定版本）
- `develop`: 开发环境分支（最新开发代码）
- `feature/*`: 功能开发分支（如 `feature/user-login`）
- `hotfix/*`: 紧急修复分支（如 `hotfix/login-bug`）

### 开发流程

```bash
# 1. 从 develop 创建功能分支
git checkout -b feature/new-feature develop

# 2. 开发并提交
git add .
git commit -m "feat: add new feature"

# 3. 推送到远程
git push origin feature/new-feature

# 4. 创建 Pull Request 到 develop

# 5. 代码审查通过后合并
```

### 提交前检查清单

- [ ] 代码已通过 ESLint 检查
- [ ] 代码已格式化（Prettier）
- [ ] 提交信息符合规范
- [ ] 相关测试已编写
- [ ] 文档已更新

## 📚 学习资源

### 官方文档

- [micro-app 官方文档](https://micro-zoe.github.io/micro-app/)
- [Vue 3 官方文档](https://vuejs.org/)
- [TypeScript 文档](https://www.typescriptlang.org/)
- [Vite 文档](https://vitejs.dev/)
- [Element Plus 文档](https://element-plus.org/)
- [Pinia 文档](https://pinia.vuejs.org/)

### 相关文章

- [Micro Frontends 官网](https://micro-frontends.org/)
- [现代前端工程化实践](https://modern-web.dev/)

## ❓ 常见问题

### Q1: 子应用无法加载怎么办？

**检查清单：**
1. 确认子应用已启动且端口正确
2. 检查 CORS 配置是否启用
3. 确认 `Access-Control-Allow-Origin` 响应头已设置
4. 检查主应用中 `url` 属性是否正确

### Q2: 样式冲突如何解决？

micro-app 默认开启样式隔离，如果仍有冲突：
1. 使用 CSS Modules
2. 添加样式前缀
3. 避免使用全局选择器

### Q3: 如何调试子应用？

```bash
# 子应用独立运行调试
cd apps/child01
pnpm dev
# 访问 http://localhost:8889
```

### Q4: Git hooks 不生效？

```bash
# 重新安装 husky
pnpm prepare

# 手动测试 hooks
npx lint-staged
npx commitlint --edit
```

### Q5: Mock 服务如何使用？

登录中心已集成 `vite-plugin-mock`：

```typescript
// mock/login.ts
export default [
  {
    url: '/api/login',
   method: 'post',
   response: () => {
     return {
       code: 200,
        data: { token: 'mock-token' }
      }
    }
  }
]
```

## 📞 技术支持

如有问题，请通过以下方式联系：

- 📧 Email: your-email@example.com
- 💬 Issues: [GitHub Issues](https://github.com/your-repo/issues)
- 📖 Wiki: [项目 Wiki](https://github.com/your-repo/wiki)

## 📄 许可证

MIT License

---

<div align="center">
  <p>Made with ❤️ by Your Team</p>
  <p>Last Updated: 2026-03-09</p>
</div>