# vite-vue-admin-template-antd

**Repository Path**: zzginfo/vite-vue-admin-template-antd

## Basic Information

- **Project Name**: vite-vue-admin-template-antd
- **Description**: 项目模板： 管理后台项目模板， 技术栈：vite，vue，ant-design-vue  等为主要技术栈。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 管理后台

基于 Vue 3 + Vite + TypeScript + Tailwind CSS + Ant Design Vue + shadcn-vue 的现代化管理后台模板。

## 技术栈

- **Vue 3.5.0** - 渐进式 JavaScript 框架
- **Vite 5.4.0** - 下一代前端构建工具
- **TypeScript 5.6.0** - JavaScript 的超集，提供类型安全
- **Tailwind CSS 3.4.14** - 实用优先的 CSS 框架（稳定版本）
- **Ant Design Vue 4.2.4** - 企业级 UI 组件库（主要 UI 库）
- **@ant-design/icons-vue 7.0.1** - Ant Design Vue 图标库
- **shadcn-vue 2.3.2** - 可复制粘贴的组件库（辅助 UI 组件）
- **Vue Router 4.4.0** - Vue.js 官方路由管理器
- **Pinia 2.2.0** - Vue 的状态管理库
- **pinia-plugin-persistedstate 2.3.0** - Pinia 持久化插件
- **dayjs 1.11.13** - 轻量级日期处理库
- **Lucide Vue Next** - 美观的图标库
- **Axios 1.13.2** - HTTP 客户端

## 功能特性

- ✅ 现代化的登录页面
- ✅ 响应式布局设计
- ✅ 侧边栏导航（基于 Ant Design Vue Layout）
- ✅ 用户认证和路由守卫
- ✅ 仪表盘首页
- ✅ Ant Design Vue 组件库（主要 UI 组件）
- ✅ shadcn-vue 2.3.2 组件演示页面（辅助 UI 组件）
- ✅ 暗色主题支持（Ant Design Vue + Tailwind CSS）
- ✅ TypeScript 类型安全
- ✅ 🔧 完善的 ESLint + Prettier 代码规范
- ✅ 🔧 Git 提交前自动代码检查（Husky + lint-staged）
- ✅ 🔧 VSCode 开发环境配置
- ✅ 🔒 请求安全机制（防重放攻击、时间戳验证、请求签名）
- ✅ 🔒 CORS 跨域配置
- ✅ 📦 API 服务层封装（统一 API 调用管理）
- ✅ 💾 Pinia 状态持久化（自动同步到 localStorage）
- ✅ 🎯 自定义指令（loading、permission、click-outside、debounce、throttle）
- ✅ 🔑 JWT Token 解析和验证
- ✅ 📋 常量统一管理

## 快速开始

### 环境配置

1. **复制环境变量文件**
```bash
# 复制环境变量示例文件
cp env.example .env.development
cp env.example .env.test
cp env.example .env.production
```

2. **配置环境变量**
根据不同环境修改对应的 `.env.*` 文件：
- `.env.development` - 开发环境配置
- `.env.test` - 测试环境配置
- `.env.production` - 生产环境配置

### 安装依赖

```bash
npm install
```

### 启动开发服务器

```bash
# 开发环境（默认）
npm run dev

# 测试环境模式
npm run dev:test

# 生产环境模式（用于本地测试生产配置）
npm run dev:prod
```

### 构建生产版本

```bash
# 默认构建（生产环境）
npm run build

# 开发环境构建
npm run build:dev

# 测试环境构建
npm run build:test

# 生产环境构建
npm run build:prod
```

### 预览构建结果

```bash
# 预览默认构建
npm run preview

# 预览测试环境构建
npm run preview:test

# 预览生产环境构建
npm run preview:prod
```

### 代码检查和格式化

```bash
# 运行 ESLint 检查并自动修复
npm run lint

# 仅检查 ESLint 错误（不修复）
npm run lint:check

# 运行 Prettier 格式化
npm run format

# 仅检查 Prettier 格式（不修复）
npm run format:check

# 运行 TypeScript 类型检查
npm run type-check
```

### UI 组件库使用

#### Ant Design Vue（主要 UI 库）

项目主要使用 **Ant Design Vue** 作为 UI 组件库，提供了丰富的企业级组件：

```vue
<template>
  <a-button type="primary">主要按钮</a-button>
  <a-table :columns="columns" :data-source="data" />
  <a-form :model="form" />
</template>

<script setup lang="ts">
import { Button, Table, Form } from 'ant-design-vue'
</script>
```

**主要特性：**
- 60+ 高质量组件
- 完整的 TypeScript 支持
- 企业级设计语言
- 丰富的主题定制能力
- 完善的文档和示例

**常用组件：**
- Layout（布局）：`a-layout`, `a-layout-header`, `a-layout-sider`, `a-layout-content`
- Navigation（导航）：`a-menu`, `a-breadcrumb`
- Data Display（数据展示）：`a-table`, `a-card`, `a-list`
- Data Entry（数据录入）：`a-form`, `a-input`, `a-select`, `a-date-picker`
- Feedback（反馈）：`a-message`, `a-notification`, `a-modal`
- 更多组件请参考 [Ant Design Vue 官方文档](https://antdv.com/)

#### shadcn-vue（辅助 UI 组件）

项目同时集成了 **shadcn-vue**，用于提供一些额外的 UI 组件：

```bash
# 添加 shadcn-vue 组件
npm run ui:add button
npm run ui:add card
npm run ui:add table

# 添加新的 v2.3.2 组件
npm run ui:add item
npm run ui:add field

# 初始化 shadcn-vue（如需重新配置）
npm run ui:init
```

**使用场景：**
- 需要高度自定义的组件
- 与 Tailwind CSS 深度集成的组件
- 可复制粘贴的组件代码

## 访问应用

启动成功后，在浏览器中访问：
- **主页**: http://localhost:3000
- **Axios测试页面**: http://localhost:3000/axios-test

## 测试 Axios 集成

1. 访问 http://localhost:3000/axios-test
2. 点击各种测试按钮验证功能：
   - GET 请求测试
   - POST 请求测试（登录）
   - PUT 请求测试
   - DELETE 请求测试
   - 认证请求测试
   - 错误处理测试
   - 文件上传测试
   - 全部测试
3. 打开浏览器开发者工具 (F12) 查看详细日志

## 默认账户

- 用户名: `admin`
- 密码: `admin123`

## 环境变量配置

### 环境变量说明

| 变量名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `VITE_APP_TITLE` | string | 管理后台 | 应用标题 |
| `VITE_APP_VERSION` | string | 1.0.0 | 应用版本 |
| `VITE_API_BASE_URL` | string | - | API 基础地址 |
| `VITE_API_TIMEOUT` | number | 30000 | API 超时时间（毫秒） |
| `VITE_APP_MOCK_ENABLED` | boolean | false | 是否启用 Mock 数据 |
| `VITE_APP_DEBUG` | boolean | false | 是否启用调试模式 |
| `VITE_APP_LOG_LEVEL` | string | info | 日志级别 (debug/info/warn/error) |
| `VITE_APP_SENTRY_DSN` | string | - | Sentry 错误监控 DSN |
| `VITE_APP_ANALYTICS_ID` | string | - | 分析工具 ID |
| `VITE_APP_DEVTOOLS` | boolean | false | 是否启用开发工具 |

### 环境配置详情

**开发环境** (默认)
- API地址: http://localhost:3001/api
- Mock模式: 启用
- 调试模式: 启用
- 开发工具: 启用

**测试环境**
- API地址: https://test-api.example.com/api
- Mock模式: 禁用
- 调试模式: 启用
- 开发工具: 启用

**生产环境**
- API地址: https://api.example.com/api
- Mock模式: 禁用
- 调试模式: 禁用
- 开发工具: 禁用
- 错误监控: 启用

## 项目结构

```
src/
├── api/            # API 服务层
│   ├── auth.ts     # 认证相关 API
│   ├── user.ts     # 用户相关 API
│   ├── types.ts    # API 类型定义
│   └── index.ts   # API 统一导出
├── assets/         # 静态资源
│   ├── index.css  # 全局样式
│   ├── theme.css  # 主题样式
│   └── theme.less  # Less 主题变量
├── components/     # 通用组件
│   └── ui/        # shadcn-vue UI 组件（辅助组件）
├── config/         # 配置文件
│   ├── env.ts     # 环境配置管理
│   └── theme.ts   # 主题配置
├── constants/      # 常量定义
│   └── index.ts   # 常量统一导出
├── directives/     # 自定义指令
│   ├── loading.ts      # 加载指令
│   ├── permission.ts   # 权限指令
│   ├── clickOutside.ts # 点击外部指令
│   ├── debounce.ts     # 防抖指令
│   ├── throttle.ts    # 节流指令
│   └── index.ts       # 指令统一导出
├── layouts/        # 布局组件
│   └── MainLayout.vue # 主布局
├── lib/           # 工具库
│   └── utils.ts   # 通用工具函数
├── plugins/       # 插件配置
│   └── dayjs.ts   # dayjs 配置
├── router/        # 路由配置
│   └── index.ts   # 路由定义
├── stores/        # 状态管理
│   ├── auth.ts    # 认证状态
│   └── theme.ts   # 主题状态
├── types/         # TypeScript 类型定义
│   ├── env.d.ts   # 环境变量类型
│   └── vue-shims.d.ts # Vue 类型声明
├── utils/         # 工具函数
│   ├── logger.ts        # 日志工具
│   ├── request.ts       # HTTP 请求工具
│   ├── env-validator.ts # 环境变量验证
│   ├── security.ts      # 安全工具（签名、防重放）
│   ├── jwt.ts          # JWT Token 工具
│   └── fix-env.ts      # 环境变量修复
├── views/         # 页面组件
│   ├── Login.vue       # 登录页
│   ├── Dashboard.vue  # 仪表盘
│   ├── Users.vue      # 用户管理
│   ├── Settings.vue   # 系统设置
│   ├── ComponentDemo.vue # 组件演示
│   ├── AxiosTest.vue  # Axios 测试
│   └── NotFound.vue   # 404 页面
└── main.ts        # 应用入口
```

## 故障排除

### 依赖安装问题

如果遇到依赖安装问题，可以尝试以下方法：

1. **清理缓存并重新安装**
   ```bash
   npm cache clean --force
   rm -rf node_modules
   rm package-lock.json
   npm install
   ```

2. **使用国内镜像**
   ```bash
   npm config set registry https://registry.npmmirror.com
   npm install
   ```

3. **检查 Node.js 版本**
   ```bash
   node --version  # 推荐 Node.js 16+ 版本
   npm --version
   ```

### 端口被占用

如果端口 3000 被占用：

1. **查找占用端口的进程** (Windows)
   ```cmd
   netstat -ano | findstr :3000
   ```

2. **结束进程** (Windows)
   ```cmd
   taskkill /PID <进程ID> /F
   ```

3. **或使用其他端口**
   ```bash
   npm run dev -- --port 3001
   ```

### 其他问题

- 如果路径中包含中文字符，可能会遇到编码问题，建议使用 UTF-8 编码的终端
- 如果仍然遇到问题，请检查控制台错误信息，或尝试在不同的终端中运行命令
- 重启开发服务器：按 `Ctrl+C` 停止，然后重新运行 `npm run dev`

## 项目功能特性

### 已完成的功能

- ✅ Vue 3 + TypeScript + Vite 项目架构
- ✅ Axios HTTP 请求封装
- ✅ 多环境配置管理
- ✅ 用户认证和路由守卫
- ✅ Ant Design Vue 企业级 UI 组件库（主要）
- ✅ shadcn-vue UI 组件库（辅助）
- ✅ Tailwind CSS 样式框架
- ✅ Pinia 状态管理
- ✅ 完整的测试页面

### Axios 集成特性

- ✅ 自动请求/响应拦截器
- ✅ 统一错误处理
- ✅ Token 自动认证
- ✅ Mock 数据支持
- ✅ 文件上传/下载
- ✅ 请求日志记录
- ✅ 请求防重放机制（时间戳 + 签名 + nonce）
- ✅ 自动 401 跳转登录

### 安全特性

- ✅ **请求防重放攻击**：每个请求包含时间戳、nonce 和签名
- ✅ **JWT Token 验证**：自动检查 token 是否过期
- ✅ **CORS 配置**：开发和生产环境 CORS 策略
- ✅ **Token 安全存储**：支持 refresh token 机制

### API 服务层

项目采用统一的 API 服务层封装，所有 API 调用都通过 `src/api/` 目录下的模块进行：

```typescript
// 使用示例
import { authApi, userApi } from '@/api'

// 登录
const response = await authApi.login({ username, password })

// 获取用户列表
const users = await userApi.getList({ page: 1, pageSize: 10 })
```

### 自定义指令

项目提供了多个实用的自定义指令：

- **v-loading**：显示加载状态
  ```vue
  <div v-loading="isLoading">内容</div>
  ```

- **v-permission**：权限控制
  ```vue
  <button v-permission="'user:create'">创建用户</button>
  ```

- **v-click-outside**：点击外部触发
  ```vue
  <div v-click-outside="handleClose">菜单</div>
  ```

- **v-debounce**：防抖处理
  ```vue
  <button v-debounce:click.300="handleClick">点击</button>
  ```

- **v-throttle**：节流处理
  ```vue
  <div v-throttle:scroll.300="handleScroll">滚动区域</div>
  ```

### 状态管理

使用 Pinia 进行状态管理，并集成了持久化插件：

```typescript
// stores/auth.ts
export const useAuthStore = defineStore('auth', () => {
  // ... 状态定义
}, {
  persist: {
    key: 'user',
    storage: localStorage,
    paths: ['user', 'token'],
  },
})
```

状态会自动同步到 localStorage，页面刷新后自动恢复。

### 常量管理

所有常量统一在 `src/constants/index.ts` 中定义：

- API 端点：`API_ENDPOINTS`
- 存储键名：`STORAGE_KEYS`
- 请求配置：`REQUEST_CONFIG`
- HTTP 状态码：`HTTP_STATUS`
- 错误消息：`ERROR_MESSAGES`
- 路由名称：`ROUTE_NAMES`
- 菜单配置：`MENU_CONFIG`

### JWT Token 处理

项目提供了完整的 JWT Token 工具函数：

```typescript
import { parseJwt, isTokenExpired, extractUserFromToken } from '@/utils/jwt'

// 解析 token
const payload = parseJwt(token)

// 检查是否过期
if (isTokenExpired(token)) {
  // token 已过期
}

// 提取用户信息
const user = extractUserFromToken(token)
```

认证状态初始化时会自动：
1. 检查 token 是否过期
2. 尝试从 token 中解析用户信息
3. 如果 token 信息不完整，调用 API 获取用户信息

## UI 组件库说明

### Ant Design Vue（主要 UI 库）

项目主要使用 **Ant Design Vue 4.2.4** 作为 UI 组件库，这是企业级 Vue UI 组件库，提供了：

- **60+ 高质量组件**：覆盖表单、表格、布局、导航等所有常用场景
- **完整的 TypeScript 支持**：所有组件都有完整的类型定义
- **企业级设计语言**：遵循 Ant Design 设计规范
- **丰富的主题定制**：支持全局主题配置和暗色模式
- **完善的文档**：[官方文档](https://antdv.com/)

**在项目中的使用：**
- 布局组件（Layout、Menu）用于主框架
- 表单组件用于数据录入
- 表格组件用于数据展示
- 反馈组件用于用户交互

### shadcn-vue（辅助 UI 组件）

项目同时集成了 **shadcn-vue 2.3.2**，用于提供：

- **可复制粘贴的组件**：组件代码直接在你的项目中，可完全自定义
- **Tailwind CSS 深度集成**：与 Tailwind CSS 完美配合
- **轻量级组件**：按需添加，不增加额外负担

**使用场景：**
- 需要高度自定义的组件
- 与 Tailwind CSS 深度集成的场景
- 补充 Ant Design Vue 没有的组件

### 样式方案

- **Ant Design Vue**：提供组件样式和主题系统
- **Tailwind CSS**：提供工具类样式和自定义样式
- **Less**：用于 Ant Design Vue 主题变量定制

两者可以完美配合使用，互不冲突。

## 开发说明

本项目使用了最新的前端技术栈，提供了完整的管理后台解决方案：

- **主要 UI 库**：Ant Design Vue（企业级组件）
- **辅助 UI 库**：shadcn-vue（可自定义组件）
- **样式方案**：Tailwind CSS + Ant Design Vue Less 变量
- **所有组件都是响应式的**，支持现代浏览器
- **完整的 TypeScript 支持**，提供类型安全