# my-vue-admin-template

**Repository Path**: xiaaoke/my-vue-admin-template

## Basic Information

- **Project Name**: my-vue-admin-template
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-31
- **Last Updated**: 2026-02-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Vue 3 + TypeScript + Element Plus 企业级后台管理系统模板

## 项目概述

这是一个基于 Vue 3 + TypeScript + Element Plus 构建的企业级后台管理系统模板，旨在为开发者提供一个开箱即用的中后台前端解决方案。

**主要亮点：**
- 基于最新的 Vue 3 + TypeScript 技术栈，提供类型安全保障
- 集成 Element Plus 组件库，美观且功能丰富
- 内置丰富的功能模块，满足企业级应用的各种需求
- 支持多语言、多布局、主题切换等国际化企业级特性
- 完善的权限控制体系，支持按钮级权限
- 集成微前端、性能监控等高级特性
- 提供丰富的封装组件和工具函数，提高开发效率

## 技术栈

- **核心框架**：Vue 3 + TypeScript
- **状态管理**：Pinia
- **路由管理**：Vue Router
- **UI 组件库**：Element Plus
- **国际化**：vue-i18n
- **图表库**：ECharts + vue-echarts
- **HTTP 客户端**：Axios
- **构建工具**：Vite
- **组件文档**：Storybook
- **性能监控**：Sentry
- **模拟数据**：Mock.js
- **Excel 处理**：xlsx
- **富文本编辑器**：WangEditor
- **微前端**：Module Federation

## 功能特性

### 1. 多语言支持 (i18n)
- 支持中文和英文两种语言
- 可通过顶部语言切换按钮快速切换
- 内置完善的国际化配置，方便扩展其他语言

### 2. 多布局切换
- 支持侧边栏菜单布局
- 响应式设计，适配不同屏幕尺寸

### 3. 响应式设计
- 适配桌面端、平板和移动设备
- 侧边栏在小屏幕下自动折叠
- 布局元素根据屏幕尺寸智能调整

### 4. 按钮级权限控制
- 基于指令的权限控制方案
- 可根据用户角色动态控制按钮的显示/隐藏
- 提供权限演示页面

### 5. 动态路由
- 支持从后端获取路由配置
- 基于用户角色动态生成路由菜单
- 内置路由守卫，处理权限验证

### 6. 主题切换
- 支持亮色/暗色两种主题模式
- 主题切换会实时应用到整个应用
- 主题偏好会保存到本地存储

### 7. 图表集成
- 集成 ECharts 图表库
- 封装常用图表组件，如折线图、柱状图、饼图等
- 提供图表示例页面

### 8. 登录鉴权
- 基于 JWT 的登录认证方案
- 登录状态管理和持久化
- 自动处理 token 过期和刷新

### 9. 微前端支持
- 基于 Module Federation 的微前端架构
- 可将应用拆分为多个独立部署的微应用

### 10. 性能监控
- 集成 Sentry 错误监控和性能追踪
- 实时捕获和上报应用错误
- 提供性能分析和优化建议

### 11. Mock 数据服务
- 内置 Mock 数据服务，支持本地开发和测试
- 模拟后端 API 响应，无需等待后端接口
- 可根据环境配置开关 Mock 服务

### 12. 组件库文档
- 集成 Storybook，提供组件可视化文档
- 支持组件交互式预览和测试
- 便于团队协作和组件复用

### 13. 公共组件封装
- **文件上传**：支持单文件/多文件上传，拖拽上传
- **图片上传**：支持图片预览、压缩、裁剪
- **表单**：封装常用表单组件，支持表单验证
- **表格**：封装表格组件，支持分页、排序、筛选
- **富文本编辑器**：集成 WangEditor，支持图文编辑
- **Excel 导入导出**：支持 Excel 文件的导入和导出功能

### 14. 常用工具函数
- **日期处理**：格式化、解析、计算等
- **字符串处理**：格式化、验证等
- **存储管理**：localStorage、sessionStorage 封装
- **网络请求**：Axios 封装，支持拦截器、请求重试等
- **环境变量**：根据不同环境加载不同配置

### 15. 全局搜索
- 支持按菜单名称和路径搜索
- 提供快捷键（Ctrl+K）触发搜索
- 搜索结果实时高亮显示

### 16. 快捷键支持
- 全局搜索：Ctrl+K
- 其他常用操作的快捷键支持

### 17. 页面缓存
- 基于 Vue 的 keep-alive 实现页面缓存
- 可通过路由 meta 控制是否缓存页面
- 提供页面缓存示例

### 18. 错误边界
- 实现 Vue 3 错误边界组件
- 捕获和处理子组件错误，防止应用崩溃
- 提供错误信息展示和重试功能

### 19. 骨架屏
- 集成 Element Plus 骨架屏组件
- 在数据加载过程中显示占位 UI
- 提升用户体验，减少加载等待感

### 20. 四环境配置
- 支持开发、测试、预发布、生产四个环境
- 每个环境有独立的配置文件
- 构建命令针对不同环境进行优化

### 21. 内置工具文档中心
- 提供各种功能的使用示例和文档
- 包括 Vue 3、TypeScript、Pinia 等技术的使用指南
- 便于团队成员快速上手和查阅

## 快速开始

### 前置要求

- **Node.js**：v16.0.0 或更高版本
- **pnpm**：v7.0.0 或更高版本

### 克隆代码

```bash
git clone <repository-url>
cd vue3-260126
```

### 安装依赖

```bash
pnpm install
```

### 环境配置

1. 复制环境变量示例文件并根据需要修改：

```bash
# 复制开发环境配置
cp .env.development .env.local

# 根据需要修改 .env.local 文件中的配置，如 API 地址等
```

### 本地运行

```bash
# 启动开发服务器
pnpm dev

# 启动开发服务器（指定模式）
pnpm dev --mode development
```

开发服务器启动后，可通过浏览器访问 `http://localhost:5173` 查看应用。

### 构建

```bash
# 构建开发环境
pnpm build:dev

# 构建测试环境
pnpm build:test

# 构建预发布环境
pnpm build:stage

# 构建生产环境
pnpm build:prod
```

构建产物将输出到 `dist` 目录。

### 其他常用命令

```bash
# 预览构建产物
pnpm preview

# 启动 Storybook 组件文档
pnpm storybook

# 构建 Storybook 组件文档
pnpm build-storybook
```

## 项目结构

```
├── src/
│   ├── assets/          # 静态资源
│   ├── components/      # 公共组件
│   │   ├── Charts/      # 图表组件
│   │   ├── CustomButton/ # 自定义按钮
│   │   ├── CustomTable/  # 自定义表格
│   │   ├── ExcelExport/  # Excel 导出
│   │   ├── ExcelUpload/  # Excel 导入
│   │   ├── FileDownload/ # 文件下载
│   │   ├── FileUpload/   # 文件上传
│   │   ├── Form/         # 表单组件
│   │   ├── GlobalSearch/ # 全局搜索
│   │   ├── ImageUpload/  # 图片上传
│   │   ├── RichTextEditor/ # 富文本编辑器
│   │   ├── Table/        # 表格组件
│   │   ├── ThemeToggle/  # 主题切换
│   │   └── ErrorBoundary/ # 错误边界
│   ├── directives/       # 自定义指令
│   ├── i18n/             # 国际化配置
│   ├── locales/          # 语言包
│   ├── mock/             # Mock 数据
│   ├── router/           # 路由配置
│   ├── store/            # Pinia 状态管理
│   ├── stories/          # Storybook 组件示例
│   ├── utils/            # 工具函数
│   │   ├── date/         # 日期处理
│   │   ├── other/        # 其他工具
│   │   ├── request/      # 请求工具
│   │   ├── storage/      # 存储工具
│   │   └── string/       # 字符串处理
│   ├── views/            # 页面组件
│   │   ├── About/        # 关于页面
│   │   ├── Admin/        # 管理页面
│   │   ├── components/   # 组件示例
│   │   ├── tools/        # 工具文档
│   │   ├── ErrorBoundaryDemo/ # 错误边界示例
│   │   ├── KeepAliveDemo/ # 页面缓存示例
│   │   ├── SkeletonDemo/ # 骨架屏示例
│   │   └── Login/        # 登录页面
│   ├── App.vue           # 根组件
│   ├── main.ts           # 入口文件
│   └── style.css         # 全局样式
├── public/               # 公共静态资源
├── .env.development      # 开发环境配置
├── .env.testing          # 测试环境配置
├── .env.staging          # 预发布环境配置
├── .env.production       # 生产环境配置
├── vite.config.ts        # Vite 配置
├── tsconfig.json         # TypeScript 配置
├── package.json          # 项目配置和依赖
└── README.md             # 项目说明
```

## 配置说明

### 环境变量配置

项目使用 Vite 的环境变量机制，支持多环境配置：

- **.env.development**：开发环境配置
- **.env.testing**：测试环境配置
- **.env.staging**：预发布环境配置
- **.env.production**：生产环境配置

**关键配置项：**

| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| `VITE_API_BASE_URL` | API 基础地址 | `http://localhost:3000/api` |
| `VITE_APP_TITLE` | 应用标题 | `Vue 3 Admin` |
| `VITE_APP_VERSION` | 应用版本 | `1.0.0` |
| `VITE_ENABLE_MOCK` | 是否启用 Mock | `true` |
| `VITE_SENTRY_DSN` | Sentry DSN | `''` |

### 核心配置

#### 1. 路由配置

路由配置位于 `src/router/index.ts`，支持静态路由和动态路由：

```typescript
// 静态路由
const staticRoutes = [
  {
    path: '/',
    name: 'home',
    component: () => import('../views/Home/index.vue'),
    meta: {
      requiresAuth: false,
      title: '首页'
    }
  },
  // 更多静态路由...
]

// 动态路由通过后端获取
```

#### 2. Pinia Store 结构

状态管理使用 Pinia，主要包含以下 Store：

- **auth**：用户认证和权限管理
- **layout**：布局相关状态
- **theme**：主题相关状态

#### 3. i18n 配置

国际化配置位于 `src/i18n/index.ts`，语言包位于 `src/locales/`：

```typescript
// 支持的语言
const messages = {
  'zh-CN': () => import('../locales/zh-CN.json'),
  'en-US': () => import('../locales/en-US.json')
}
```

#### 4. 主题配置

主题配置通过 Element Plus 的主题定制和自定义 CSS 变量实现，支持亮色和暗色两种模式。

## 使用指南

### 1. 添加新页面

1. 在 `src/views/` 目录下创建新的页面组件
2. 在 `src/router/index.ts` 中添加路由配置
3. 在 `src/App.vue` 的菜单配置中添加菜单项

### 2. 添加新菜单项

#### 静态菜单

在 `src/App.vue` 的 `menuItems` 数组中添加新的菜单项：

```typescript
const menuItems = ref([
  // 现有菜单项...
  {
    title: '新页面',
    path: '/new-page',
    icon: Document
  }
])
```

#### 动态菜单

动态菜单通过后端 API 获取，需要在后端配置路由信息，前端会自动处理。

### 3. 实现权限控制

#### 路由级别权限

在路由配置中添加 `requiresAuth` 和 `roles` 元信息：

```typescript
{
  path: '/admin',
  name: 'admin',
  component: () => import('../views/Admin/index.vue'),
  meta: {
    requiresAuth: true,
    roles: ['admin'], // 只有 admin 角色可以访问
    title: '管理页面'
  }
}
```

#### 按钮级别权限

使用 `v-permission` 指令控制按钮显示：

```vue
<el-button v-permission="['admin', 'editor']" type="primary">
  只有管理员和编辑可以看到
</el-button>
```

### 4. 使用封装的公共组件

#### 文件上传

```vue
<template>
  <FileUpload 
    :action="uploadUrl" 
    :multiple="true"
    @success="handleSuccess"
  />
</template>

<script setup lang="ts">
import FileUpload from '@/components/FileUpload/index.vue'

const uploadUrl = 'https://api.example.com/upload'

const handleSuccess = (response: any) => {
  console.log('上传成功:', response)
}
</script>
```

#### 表格组件

```vue
<template>
  <CustomTable 
    :data="tableData" 
    :columns="columns"
    :pagination="pagination"
    @page-change="handlePageChange"
  />
</template>

<script setup lang="ts">
import CustomTable from '@/components/CustomTable/index.vue'

const tableData = ref([...])
const columns = ref([...])
const pagination = ref({ page: 1, size: 10, total: 100 })

const handlePageChange = (page: number, size: number) => {
  console.log('页码变化:', page, size)
}
</script>
```

### 5. 使用工具函数

#### 日期处理

```typescript
import { formatDate } from '@/utils/date'

const formattedDate = formatDate(new Date(), 'YYYY-MM-DD HH:mm:ss')
console.log(formattedDate) // 2024-01-01 12:00:00
```

#### 网络请求

```typescript
import request from '@/utils/request'

// GET 请求
const { data } = await request.get('/api/users')

// POST 请求
const { data } = await request.post('/api/users', { name: '张三' })
```

### 6. 进行国际化

1. 在语言包文件中添加翻译：

```json
// src/locales/zh-CN.json
{
  "nav": {
    "home": "首页",
    "newPage": "新页面"
  }
}

// src/locales/en-US.json
{
  "nav": {
    "home": "Home",
    "newPage": "New Page"
  }
}
```

2. 在组件中使用：

```vue
<template>
  <div>{{ t('nav.newPage') }}</div>
</template>

<script setup lang="ts">
import { useI18n } from 'vue-i18n'

const { t } = useI18n()
</script>
```

### 7. 切换主题

主题切换通过 `ThemeToggle` 组件实现，也可以通过 Pinia store 手动切换：

```typescript
import { useThemeStore } from '@/store/theme'

const themeStore = useThemeStore()

// 切换到暗色主题
themeStore.setDarkTheme(true)

// 切换到亮色主题
themeStore.setDarkTheme(false)
```

### 8. 处理 Mock 数据

在 `src/mock/` 目录下添加 Mock 数据配置：

```typescript
// src/mock/user.ts
import { MockMethod } from 'vite-plugin-mock'

export default [
  {
    url: '/api/users',
    method: 'get',
    response: () => {
      return {
        code: 200,
        data: [
          { id: 1, name: '张三', email: 'zhangsan@example.com' },
          { id: 2, name: '李四', email: 'lisi@example.com' }
        ]
      }
    }
  }
] as MockMethod[]
```

## 贡献指南

### 提交 Issue

如果您发现了 bug 或有新的功能建议，请在 GitHub 仓库中提交 Issue。

### 提交 Pull Request

1. Fork 仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 打开 Pull Request

## 许可证

MIT License

## 致谢

- [Vue 3](https://vuejs.org/)
- [Element Plus](https://element-plus.org/)
- [Pinia](https://pinia.vuejs.org/)
- [Vue Router](https://router.vuejs.org/)
- [ECharts](https://echarts.apache.org/)
- [Storybook](https://storybook.js.org/)
- [Sentry](https://sentry.io/)

---

**注意**：本模板仅供学习和开发使用，生产环境请根据实际需求进行适当调整和优化。