# vue-federation-starter

**Repository Path**: cherng/vue-federation-starter

## Basic Information

- **Project Name**: vue-federation-starter
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-11
- **Last Updated**: 2025-11-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Vue Federation Starter

**🚀 现代化前端脚手架 | 📦 模块联邦架构 | ⚡ 开箱即用**

## ✨ 项目简介

这是一个基于 **Vue 3 + TypeScript + Vite** 的现代化前端脚手架项目，使用**模块联邦（Module Federation）**实现微前端架构。本项目作为子模块，可以被其他应用引用和集成，同时也可以引用其他模块。项目集成了当前主流的前端开发技术栈和最佳实践。

## 技术栈

- **核心框架：** Vue 3.4.0
- **开发语言：** TypeScript 5.6.2
- **构建工具：** Vite 6.0.2
- **微前端方案：** Module Federation
- **状态管理：** Pinia 2.3.0
- **UI 框架：** Element Plus 2.9.0
- **路由管理：** Vue Router 4.2.0
- **HTTP 客户端：** Axios 1.7.9
- **数据可视化：** ECharts 5.5.1

## 模块联邦配置

项目使用 Vite 的模块联邦插件 `@originjs/vite-plugin-federation` 实现微前端架构，并实现了智能的模块动态加载机制：

### 模块动态加载

项目实现了一个智能的远程模块加载器（`src/utils/federation.ts`），具有以下特性：

```typescript
// 动态加载远程模块
const loadedComponents = await getRemoteEntries(name, moduleName)
```

核心功能：

- 📦 自动从 registry.json 获取模块注册信息
- 🔄 支持模块动态加载和热更新
- 💾 内置模块缓存机制（1小时过期）
- 🎯 支持按名称和类型筛选模块
- 🛡️ 完善的错误处理和日志记录

使用示例：

```typescript
// 加载所有路由模块
const routes = await getRemoteEntries(undefined, 'routes')

// 加载指定名称的模块
const menuComponents = await getRemoteEntries('menu', 'components')
```

### 模块暴露

```javascript
// 暴露的模块配置
{
  name: 'xxxModule',           // 模块名称
  filename: 'xxxEntry.js',     // 入口文件名
  exposes: {
    './routes': './src/routes/index.ts'  // 暴露路由配置
  }
}
```

### 共享依赖

以下依赖被配置为共享模块，避免重复加载：

- vue
- vue-router
- pinia
- dayjs
- echarts
- axios
- sass
- element-plus

## 目录结构

```
src/
├── api/          # API 接口定义
│   ├── login.ts  # 登录相关接口
│   └── demo.ts   # 示例接口
├── components/   # 全局组件
├── config/       # 项目配置
├── layouts/      # 布局组件
├── routes/       # 路由配置
├── stores/       # Pinia 状态管理
│   ├── modules/  # 状态模块
│   │   ├── app.ts     # 应用状态
│   │   ├── auth.ts    # 认证状态
│   │   ├── cache.ts   # 缓存状态
│   │   └── user.ts    # 用户状态
├── styles/       # 全局样式
├── types/        # TypeScript 类型定义
├── utils/        # 工具函数
│   ├── federation.ts      # 模块联邦工具
│   ├── initGlobalData.ts  # 全局数据初始化
│   └── ...
├── views/        # 页面组件
└── App.vue       # 根组件
```

## 快速开始

### 环境要求

- Node.js 22.14.0 (严格要求此版本)
- npm 或 yarn

### 安装依赖

```bash
npm install
# 或
yarn install
```

### 开发命令

```bash
# 启动开发服务器
npm run dev

# 构建生产版本
npm run build

# 预览生产构建
npm run preview

# 代码格式化
npm run format

# 代码检查
npm run lint

# 修复代码问题
npm run lint:fix

# 类型检查
npm run type-check

# 单元测试
npm run test

# 清理构建产物
npm run clean
```

## 环境变量配置

项目使用 `.env` 文件管理环境变量:

```
# 网站CDN
VITE_APP_BASE_URL='https://example.com'

# 是否启用联邦
VITE_APP_TYPE=federation

# 请求域名
VITE_APP_BASE_API=https://api.example.com
```

## 路由结构

项目支持两种路由模式:

1. **联邦模式(federation)**: 从远程获取路由配置并合并
2. **独立模式**: 使用本地路由配置

路由守卫功能:

- 白名单路由检查
- 登录状态检查
- 用户信息完整性检查
- 自动跳转到登录页或首页

## 状态管理(Pinia)

项目使用 Pinia 进行状态管理，并支持状态持久化:

- **app**: 应用全局状态
- **auth**: 用户认证状态
- **cache**: 缓存管理
- **setting**: 用户设置
- **user**: 用户信息

## 开发规范

- 使用 TypeScript 编写代码
- 遵循 ESLint 和 Prettier 配置的代码规范
- 组件和工具函数需要编写清晰的类型定义
- 使用 Composition API 编写 Vue 组件
- 遵循模块化的开发方式

## 项目特点

1. **模块化设计**
   - 基于 Pinia 的状态管理
   - 模块化的路由配置
   - 组件自动导入

2. **TypeScript 支持**
   - 完整的类型定义
   - 智能的类型推导
   - 更好的开发体验

3. **UI 组件库**
   - 集成 Element Plus
   - 图标组件支持
   - 响应式设计

4. **开发工具链**
   - Vite 快速热重载
   - ESLint 代码检查
   - Prettier 代码格式化
   - TypeScript 类型检查

5. **全局数据初始化机制**
   - 支持自动初始化全局数据（`src/utils/initGlobalData.ts`）
   - 可配置单次初始化或每次加载初始化
   - 内置错误处理和状态管理

## 注意事项

1. 确保使用正确的 Node.js 版本（22.14.0）
2. 开发前请仔细阅读代码规范文档
3. 提交代码前进行代码格式化和类型检查
4. 保持良好的代码注释和文档习惯

## 构建部署

项目使用 Vite 进行构建，构建产物位于 `dist` 目录。

```bash
# 构建生产版本
npm run build

# 清理构建产物
npm run clean
```

## 微前端集成

### 注册远程模块

在 `registry.json` 中注册模块:

```json
[
  {
    "name": "xxxModule",
    "path": "front-pc-scaffold/main"
  }
]
```

### 命名规范

- 模块名称必须以 "Module" 结尾
- 入口文件名必须以 "Entry.js" 结尾
- 例如：xxxModule -> xxxEntry.js

## 贡献指南

1. Fork 本仓库
2. 创建特性分支
3. 提交变更
4. 发起 Pull Request

## 许可证

[MIT License](LICENSE)

## 技术实现细节

### 模块注册机制

项目使用 `registry.json` 作为模块注册中心，存储所有可用模块的信息：

```json
[
  {
    "name": "xxxModule",
    "path": "front-pc-scaffold"
  }
]
```

### 模块加载流程

1. **入口获取**
   - 从 `registry.json` 获取所有模块入口信息
   - 自动构建模块入口URL（例如：`baseUrl/front-pc-menu/menuEntry.js`）
   - 支持按模块名称过滤

2. **动态导入**
   - 使用动态 import 加载远程模块
   - 支持指定加载特定类型的模块（routes、components等）
   - 自动处理模块加载失败的情况

3. **缓存策略**
   - 使用 Map 结构缓存已加载的模块
   - 缓存时间为1小时，过期后自动重新加载
   - 支持按模块名称和类型分别缓存

4. **错误处理**
   - 完善的错误捕获和日志记录
   - 模块加载失败时优雅降级
   - 详细的错误信息输出

### 使用注意事项

1. **模块命名规范**
   - 模块名称必须以 "Module" 结尾
   - 入口文件名必须以 "Entry.js" 结尾
   - 例如：xxxModule -> xxxEntry.js

2. **模块导出规范**
   - 模块必须通过 `exposes` 配置暴露接口
   - 导出内容必须符合类型定义
   - 建议使用 TypeScript 编写模块接口

3. **性能优化**
   - 合理使用缓存机制
   - 避免频繁加载相同模块
   - 按需加载模块内容

### 全局数据初始化

项目实现了一个自执行的全局数据初始化机制：

```typescript
// 如果要使用则在所有页面文件引入
import '@/utils/initGlobalData'
```

```typescript
// 是否使用单次初始化
let isInitialized = false

// 自执行初始化函数
;(async () => {
 // 当前是单次初始化
 if (isInitialized) {
  return
 }

 try {
  isInitialized = true
  // 在此处添加初始化全局数据的逻辑
 } catch (error) {
  console.error('初始化全局数据失败:', error)
 }
})()
```

使用场景：

1. 需要在应用启动时初始化全局数据
2. 可以在页面中引入该文件
3. 支持配置为单次初始化或多次初始化