# vite-vue-admin-template-shadcn

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

## Basic Information

- **Project Name**: vite-vue-admin-template-shadcn
- **Description**: 项目模板： 管理后台项目模板， 技术栈：vite，vue，shadcn-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-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 管理后台

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

## 技术栈

- **Vue 3.5.0** - 渐进式 JavaScript 框架
- **Vite 5.4.0** - 下一代前端构建工具
- **TypeScript 5.6.0** - JavaScript 的超集，提供类型安全
- **Tailwind CSS 3.4.14** - 实用优先的 CSS 框架（稳定版本）
- **shadcn-vue 2.3.2** - 可复制粘贴的组件库（🆕 最新版本）
- **Vue Router 4.4.0** - Vue.js 官方路由管理器
- **Pinia 2.2.0** - Vue 的状态管理库
- **dayjs 1.11.13** - 轻量级日期处理库
- **Lucide Vue Next** - 美观的图标库

## 功能特性

- ✅ 现代化的登录页面
- ✅ 响应式布局设计
- ✅ 侧边栏导航
- ✅ 用户认证和路由守卫
- ✅ 仪表盘首页
- ✅ 🆕 shadcn-vue 2.3.2 组件演示页面
- ✅ 🆕 新的 Item 和 Field 组件支持
- ✅ 暗色主题支持
- ✅ TypeScript 类型安全
- ✅ 🔧 完善的 ESLint + Prettier 代码规范
- ✅ 🔧 Git 提交前自动代码检查（Husky + lint-staged）
- ✅ 🔧 VSCode 开发环境配置

## 快速开始

### 环境配置

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
```

### shadcn-vue 组件管理

```bash
# 添加组件
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
```

## 访问应用

启动成功后，在浏览器中访问：
- **主页**: 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/
├── assets/          # 静态资源
├── components/      # 通用组件
├── config/          # 配置文件
│   └── env.ts       # 环境配置管理
├── layouts/         # 布局组件
├── lib/            # 工具库
├── plugins/        # 插件配置
├── router/         # 路由配置
├── stores/         # 状态管理
├── types/          # TypeScript 类型定义
├── utils/          # 工具函数
│   ├── logger.ts   # 日志工具
│   ├── request.ts  # HTTP 请求工具
│   └── env-validator.ts # 环境变量验证
├── views/          # 页面组件
└── 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 请求封装
- ✅ 多环境配置管理
- ✅ 用户认证和路由守卫
- ✅ shadcn-vue UI 组件库
- ✅ Tailwind CSS 样式框架
- ✅ Pinia 状态管理
- ✅ 完整的测试页面

### Axios 集成特性

- ✅ 自动请求/响应拦截器
- ✅ 统一错误处理
- ✅ Token 自动认证
- ✅ Mock 数据支持
- ✅ 文件上传/下载
- ✅ 请求日志记录

## 开发说明

本项目使用了最新的前端技术栈，提供了完整的管理后台解决方案。所有组件都是响应式的，支持现代浏览器。