# Vue3 template

**Repository Path**: xiaaoke/vue3-template

## Basic Information

- **Project Name**: Vue3 template
- **Description**: vue3企业级搭建模板
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-09
- **Last Updated**: 2026-02-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Vue3 项目模板

## 项目背景

本项目是一个基于 Vue 3 + Vite 的现代化前端项目模板，旨在为开发团队提供一套标准化、高性能的前端开发框架。项目集成了完整的用户认证系统、性能优化技术和开发工具链，为快速构建企业级应用提供了坚实的基础。

## 功能特性

### 核心功能

- **用户认证系统**：完整的登录、登出、权限控制流程
- **权限管理**：基于路由和指令的细粒度权限控制
- **性能优化**：代码分割、组件懒加载、虚拟滚动、防抖节流、图片优化
- **国际化支持**：内置 i18n 国际化方案，支持带参数的翻译文本
- **主题切换**：支持明暗主题切换
- **响应式设计**：适配各种设备屏幕
- **路由缓存**：基于标签页的路由缓存管理，提升用户体验
- **组件标准化**：统一的组件命名规范，与菜单名称保持一致
- **面包屑导航**：支持多语言的面包屑导航组件
- **标签页管理**：完整的标签页添加、切换、关闭功能
- **菜单搜索**：支持快速搜索和定位菜单项
- **个人中心**：用户个人信息管理和账户安全设置
- **API 模拟**：内置 Mock 数据功能，支持开发环境下的 API 模拟

### 开发工具链

- **ESLint + Prettier + Oxlint**：代码规范和格式化
- **TypeScript**：类型安全
- **Vite**：快速构建和热更新
- **Pinia**：轻量级状态管理
- **Vue Router**：路由管理
- **Element Plus**：UI 组件库
- **Vitest**：单元测试
- **Husky + Lint-Staged**：Git 工作流规范
- **VueUse**：实用的 Vue 组合式 API 工具集
- **Mock.js**：API 模拟工具
- **Sass**：CSS 预处理器

## 技术栈

| 类别        | 技术              | 版本           |
| ----------- | ----------------- | -------------- |
| 前端框架    | Vue               | 3.5.27         |
| 状态管理    | Pinia             | 3.0.4          |
| 路由管理    | Vue Router        | 5.0.1          |
| UI 库       | Element Plus      | 2.13.2         |
| 构建工具    | Vite              | 7.3.1          |
| 类型系统    | TypeScript        | 5.9.3          |
| 代码规范    | ESLint + Prettier | 9.39.2 + 3.8.1 |
| 国际化      | Vue I18n          | 11.2.8         |
| 测试框架    | Vitest            | 4.0.18         |
| HTTP 客户端 | Axios             | 1.13.5         |
| 工具库      | Lodash            | 4.17.23        |

## 环境要求

- Node.js: ^20.19.0 || >=22.12.0
- pnpm: >=8.0.0

## 安装步骤

### 1. 克隆仓库

```sh
git clone <repository-url>
cd vue3-templaet
```

### 2. 安装依赖

```sh
pnpm install
```

### 3. 启动开发服务器

```sh
pnpm dev
```

### 4. 构建生产版本

```sh
pnpm build
```

### 5. 运行测试

```sh
pnpm test:unit
```

### 6. 代码检查

```sh
pnpm lint
```

## 基本使用方法

### 路由配置

路由配置位于 `src/router/modules/` 目录，可根据功能模块添加新的路由配置。

### 组件开发

组件开发遵循 Vue 3 Composition API 规范，建议使用 `<script setup>` 语法。

### 状态管理

使用 Pinia 进行状态管理，状态模块位于 `src/stores/` 目录。

### 权限控制

使用 `v-permission` 指令进行权限控制：

```vue
<el-button v-permission="['manage:user']">管理用户</el-button>
```

### 性能优化

项目提供了多种性能优化技术的示例，位于 `src/views/PerformanceView/` 目录：

- **代码分割**：按需加载路由和组件
- **组件懒加载**：使用 defineAsyncComponent 实现
- **虚拟滚动**：处理大型列表
- **防抖节流**：优化事件处理
- **图片优化**：懒加载和现代格式

### 路由缓存

项目实现了基于标签页的路由缓存管理功能，位于 `src/views/DocumentationView/RouteCacheView/` 目录：

- **标签页管理**：支持添加、切换、关闭标签页
- **缓存控制**：自动管理组件缓存，限制最大缓存数量
- **缓存状态**：可视化展示缓存状态和管理选项

## 项目结构

```
src/
├── assets/            # 静态资源
├── components/        # 公共组件
│   ├── LanguageSwitcher/  # 语言切换组件
│   ├── TheWelcome/         # 欢迎组件
│   ├── WelcomeItem/        # 欢迎项组件
│   ├── icons/              # 图标组件
│   └── RouteCacheMenu.vue  # 路由缓存菜单组件
├── directives/        # 自定义指令
│   └── permission.ts       # 权限控制指令
├── layout/            # 布局组件
│   ├── components/         # 布局子组件
│   │   ├── BreadcrumbHeader.vue     # 面包屑头部
│   │   ├── BreadcrumbNavigation.vue # 面包屑导航
│   │   ├── ContainerFooter.vue      # 容器底部
│   │   ├── HeaderActions.vue        # 头部操作
│   │   ├── MenuAside.vue            # 侧边菜单
│   │   ├── MenuSearch.vue           # 菜单搜索
│   │   └── TabManager.vue           # 标签页管理
│   └── IndexPage.vue       # 布局主页
├── locales/           # 国际化资源
│   ├── en/                 # 英文语言包
│   ├── zh-CN/              # 中文语言包
│   └── index.ts            # 国际化配置
├── router/            # 路由配置
│   ├── modules/            # 路由模块
│   │   ├── documentation.ts   # 文档路由
│   │   ├── fullPage.ts        # 全屏页面路由
│   │   ├── main.ts            # 主路由
│   │   ├── performance.ts     # 性能优化路由
│   │   └── tools.ts           # 工具路由
│   └── index.ts            # 路由配置入口
├── stores/            # 状态管理
│   ├── counter.ts           # 计数器状态
│   ├── layout.ts             # 布局状态
│   └── user.ts               # 用户状态
├── styles/            # 样式文件
│   ├── base.scss            # 基础样式
│   ├── element-plus.scss     # Element Plus 样式
│   └── main.scss             # 主样式
├── types/             # 类型定义
│   └── element-plus.d.ts     # Element Plus 类型定义
├── utils/             # 工具函数
│   ├── mock/                 # Mock 数据
│   │   ├── axios-mock.ts       # Axios Mock 拦截器
│   │   └── index.ts            # Mock 数据配置
│   ├── cookie.ts             # Cookie 工具
│   ├── date.js               # 日期工具
│   ├── request.js            # 请求工具
│   ├── storage.js            # 存储工具
│   └── validate.js           # 验证工具
├── views/             # 页面组件
│   ├── AboutView/            # 关于页面
│   ├── AdminView/             # 管理员页面
│   ├── DocumentationView/     # 文档页面
│   │   ├── CodeStandardView/      # 代码规范视图
│   │   ├── GitWorkflowView/        # Git 工作流视图
│   │   ├── ProjectDocumentationView/ # 项目文档体系视图
│   │   └── RouteCacheView/         # 路由缓存视图
│   ├── ErrorView/             # 错误页面
│   │   ├── 403Page.vue           # 403 页面
│   │   └── 404Page.vue           # 404 页面
│   ├── HomeView/              # 首页
│   ├── LoginView/             # 登录页面
│   ├── NoteView/               # 笔记管理页面
│   ├── PerformanceView/        # 性能优化页面
│   │   ├── CodeSplittingView/       # 代码分割视图
│   │   ├── ComponentLazyLoadingView/ # 组件懒加载视图
│   │   ├── DebounceThrottleView/    # 防抖节流视图
│   │   ├── ImageOptimizationView/   # 图片优化视图
│   │   └── VirtualScrollingView/    # 虚拟滚动视图
│   ├── PersonalView/           # 个人中心页面
│   ├── ToolsDemoView/          # 工具演示页面
│   └── UserView/               # 用户页面
├── App.vue            # 根组件
├── main.ts            # 入口文件
└── vite-env.d.ts      # Vite 环境类型
```

## 代码规范

- **ESLint**：代码质量和语法检查
- **Prettier**：代码格式化
- **TypeScript**：类型安全
- **Git Hooks**：提交前代码检查

## 贡献指南

请参考 [CONTRIBUTING.md](./CONTRIBUTING.md) 文件了解如何为项目贡献代码。

## 常见问题

### 1. 安装依赖失败

**解决方案**：确保 Node.js 和 pnpm 版本符合要求，尝试清除缓存后重新安装：

```sh
pnpm cache clean
pnpm install
```

### 2. 开发服务器启动失败

**解决方案**：检查端口是否被占用，尝试使用不同端口启动：

```sh
pnpm dev --port 3000
```

### 3. 构建失败

**解决方案**：检查 TypeScript 类型错误，运行类型检查：

```sh
pnpm type-check
```

### 4. 权限控制不生效

**解决方案**：确保用户登录后正确获取了权限信息，检查权限指令的使用是否正确。

### 5. 性能优化效果不明显

**解决方案**：使用浏览器开发者工具分析性能瓶颈，根据具体场景选择合适的优化技术。

### 6. 路由缓存不生效

**解决方案**：确保组件已正确设置 `name` 属性，并且路由配置中包含 `name` 字段。检查 `layoutStore.addToCache` 方法是否正确调用。

## 许可证

MIT License

## 联系方式

如有问题或建议，请通过 GitHub Issues 或项目讨论区提出。