# vue3-element-admin-vite

**Repository Path**: ncepu-bj/vue3-element-admin-vite

## Basic Information

- **Project Name**: vue3-element-admin-vite
- **Description**: 后台管理起步项目vue3-element-admin-vite，是基于 Vue3 + Vite4+ TypeScript5 + Element-Plus + Pinia 等最新主流技术栈构建的后台管理前端模板
- **Primary Language**: JavaScript
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2023-12-06
- **Last Updated**: 2025-11-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<p align="center">
    <img src="https://img.shields.io/badge/Vue-3.3.8-brightgreen.svg"/>
    <img src="https://img.shields.io/badge/Vite-4.5.0-green.svg"/>
    <img src="https://img.shields.io/badge/TypeScript-5.2.2-blue.svg"/>
    <img src="https://img.shields.io/badge/Element Plus-2.4.2-blue.svg"/>
    <img src="https://img.shields.io/badge/Pinia-2.1.7-yellow.svg"/>
    <img src="https://img.shields.io/badge/license-MIT-green.svg"/>
</p>

<p align="center">
 <a target="_blank" href="https://juejin.cn/post/7228990409909108793">📖 官方文档</a> | 
 <a target="_blank" href="http://vue3.youlai.tech">🌐 在线预览</a> | 
 <a target="_blank" href="https://docs.apipost.net/docs/detail/547a92257cca000?target_id=518513">📡 接口文档</a>
</p>

---

## 📖 项目介绍

基于 **Vue3 + Vite4 + TypeScript5 + Element-Plus + Pinia** 等最新主流技术栈构建的后台管理前端模板。

本项目是 [vue-element-admin](https://github.com/PanJiaChen/vue-element-admin) 的 Vue3 升级版本，保持简洁易用的设计理念，无过度封装，降低学习成本。

### ✨ 核心特性

- 🚀 **最新技术栈** - 采用 Vue3、Vite4、TypeScript5 等前沿技术开发
- 📦 **开箱即用** - 无过度封装，易上手，减少学习成本
- 🔐 **完整权限系统** - 内置用户、角色、菜单、字典、部门等权限管理功能
- 🌍 **国际化支持** - 内置中英文国际化方案，支持多语言切换
- 🎨 **主题定制** - 支持亮色/暗黑模式，可自定义主题色
- 📱 **响应式布局** - 支持桌面端和移动端自适应
- 🔧 **工程化规范** - 集成 ESLint、Prettier、Stylelint、Husky 等工具
- 📝 **Git 提交规范** - 使用 Commitizen + Commitlint 规范化提交
- 🔌 **真实接口** - 提供配套后端接口，真实数据（非 Mock）
- ⚡ **性能优化** - 使用 Vite 构建，开发体验极速，生产包体积小
- 🛠️ **Sass 优化** - 使用 sass-embedded 现代编译器，无废弃警告

## 🖥️ 项目预览

### 在线体验

- **预览地址**：[http://vue3.youlai.tech/](http://vue3.youlai.tech/)
- **接口文档**：[ApiPost 在线文档](https://docs.apipost.net/docs/detail/547a92257cca000?target_id=518513)

### 界面展示

**控制台（暗黑模式）**

![暗黑模式](https://foruda.gitee.com/images/1687755822903300961/a4d63e22_716974.png)

**接口文档**

![接口文档](https://foruda.gitee.com/images/1687755822857820115/96054330_716974.png)

**权限管理系统**

| 用户管理 | 角色管理 |
| :------: | :------: |
| ![用户管理](https://foruda.gitee.com/images/1687755822816437081/b7620905_716974.png) | ![角色管理](https://foruda.gitee.com/images/1687755822852085747/c13a4d19_716974.png) |

| 菜单管理 | 字典管理 |
| :------: | :------: |
| ![菜单管理](https://foruda.gitee.com/images/1687755822966247550/4d4f8118_716974.png) | ![字典管理](https://foruda.gitee.com/images/1687755822828758939/8035a91f_716974.png) |

## 🔗 项目地址

**本项目仓库**：[https://gitee.com/ncepu-bj/vue3-element-admin-vite](https://gitee.com/ncepu-bj/vue3-element-admin-vite)

**原始项目**：

| 项目 | Gitee | Github | GitCode |
| :--: | :---: | :----: | :-----: |
| **前端** | [vue3-element-admin](https://gitee.com/youlaiorg/vue3-element-admin) | [vue3-element-admin](https://github.com/youlaitech/vue3-element-admin) | [vue3-element-admin](https://gitcode.net/youlai/vue3-element-admin) |
| **后端** | [youlai-boot](https://gitee.com/youlaiorg/youlai-boot) | [youlai-boot](https://github.com/haoxianrui/youlai-boot) | [youlai-boot](https://gitcode.net/youlai/youlai-boot) |

## 🛠️ 技术栈

### 核心框架

- **Vue 3.3.8** - 渐进式 JavaScript 框架
- **Vite 4.5.0** - 下一代前端构建工具
- **TypeScript 5.2.2** - JavaScript 的超集，提供类型支持

### UI 框架

- **Element Plus 2.4.2** - 基于 Vue 3 的组件库
- **UnoCSS 0.51.13** - 即时按需原子化 CSS 引擎

### 状态管理与路由

- **Pinia 2.1.7** - Vue 3 官方推荐的状态管理库
- **Vue Router 4.2.5** - Vue.js 官方路由管理器

### 工具库

- **Axios 1.6.0** - HTTP 客户端
- **VueUse 10.5.0** - Vue 组合式 API 工具集
- **Day.js 1.11.10** - 轻量级日期处理库
- **ECharts 5.4.3** - 数据可视化图表库
- **Vue I18n 9.2.2** - 国际化插件

### 开发工具

- **ESLint** - 代码质量检查
- **Prettier** - 代码格式化
- **Stylelint** - 样式代码检查
- **Husky** - Git hooks 工具
- **Commitizen** - 规范化 Git 提交
- **sass-embedded** - 现代 Sass 编译器

## 🛠️ 环境准备

### 基础环境

| 环境 | 版本要求 | 下载地址 |
| :--: | :------: | :------: |
| **Node.js** | >= 16.0.0 | [官网下载](http://nodejs.cn/download) |
| **pnpm** | 最新版本 | `npm install -g pnpm` |
| **VSCode** | 最新版本 | [官网下载](https://code.visualstudio.com/Download) |

### VSCode 插件（必装）

| 插件名称 | 说明 | 备注 |
| :------: | :--: | :--: |
| `Vue Language Features (Volar)` | Vue 3 语言支持 | ✅ 必装 |
| `TypeScript Vue Plugin (Volar)` | TypeScript 支持 | ✅ 必装 |
| ~~`Vetur`~~ | Vue 2 插件 | ❌ 必须禁用 |

![VSCode插件](https://foruda.gitee.com/images/1687755823108948048/d0198b2d_716974.png)

## 🚀 快速开始

### 1️⃣ 克隆项目

```bash
# 克隆本项目
git clone https://gitee.com/ncepu-bj/vue3-element-admin-vite.git

# 进入项目目录
cd vue3-element-admin-vite
```

### 2️⃣ 安装依赖

```bash
# 安装 pnpm（如果未安装）
npm install -g pnpm

# 安装项目依赖
pnpm install
```

### 3️⃣ 启动开发服务器

```bash
# 开发模式运行
pnpm run dev

# 服务将运行在 http://localhost:3000
```

### 4️⃣ 构建生产版本

```bash
# 生产环境打包
pnpm run build:prod

# 打包文件将生成在 dist/ 目录
```

## ⚙️ 项目配置

### 环境变量

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

**开发环境** (`.env.development`)

```bash
# 开发服务器端口
VITE_APP_PORT = 3000

# API 请求前缀
VITE_APP_BASE_API = '/api_1'

# 后端 API 地址（可选以下三种）
VITE_APP_API_URL = 'http://api.experiment.ncepu.edu.cn/api_1'  # 线上接口（默认）
# VITE_APP_API_URL = 'http://localhost:8989'                    # 本地接口
# VITE_APP_API_URL = 'http://localhost:3000'                    # Mock 数据

# Sass 警告静默（已配置）
SASS_SILENCE_DEPRECATIONS=legacy-js-api
```

**生产环境** (`.env.production`)

```bash
# 根据实际生产环境配置
VITE_APP_BASE_API = '/prod-api'
VITE_APP_API_URL = 'https://your-production-api.com'
```

### Sass 配置优化 ✨

项目已完成 Sass 编译器优化，消除了所有废弃警告：

- ✅ 使用 `sass-embedded` 替代旧版 `sass`
- ✅ Vite 配置中启用 `modern-compiler` API
- ✅ 全局静默 `legacy-js-api` 警告
- ✅ 跨平台环境变量支持（使用 `cross-env`）
- ✅ 创建 `.sassrc.js` 全局配置文件

**配置文件**：

- `vite.config.ts` - Vite 构建配置
- `.sassrc.js` - Sass 全局配置
- `.env.development` - 环境变量配置
- `package.json` - npm 脚本配置

### 自动导入配置

项目使用 `unplugin-auto-import` 和 `unplugin-vue-components` 实现自动导入：

- **Vue API**：`ref`、`reactive`、`computed` 等无需手动导入
- **Element Plus**：组件和 API 自动按需导入
- **图标**：`@element-plus/icons-vue` 自动注册

> 💡 **提示**：组件类型声明已生成，如需更新请临时开启 `vite.config.ts` 中的 `dts: true`

## 📡 接口支持

### 线上接口（默认）

本项目使用的接口地址：

| 类型 | 地址 |
| :--: | :--: |
| **API 调用地址** | `http://api.experiment.ncepu.edu.cn/api_1` |
| **接口文档** | [ApiPost 在线文档](https://docs.apipost.net/docs/detail/547a92257cca000?target_id=518513) |

**接口功能**：

- 用户登录/登出
- 学生信息管理（增删改查）
- 权限验证

### 原始项目接口

| 类型 | 地址 |
| :--: | :--: |
| **API 调用地址** | [https://vapi.youlai.tech](https://vapi.youlai.tech) |
| **接口文档** | [Apifox 在线文档](https://www.apifox.cn/apidoc/shared-195e783f-4d85-4235-a038-eec696de4ea5) |
| **OpenAPI 文档** | [http://vapi.youlai.tech/v3/api-docs](http://vapi.youlai.tech/v3/api-docs) |

### 本地接口配置

如需使用本地后端接口，请按以下步骤操作：

1. **获取后端源码**

   ```bash
   git clone https://gitee.com/youlaiorg/youlai-boot.git
   ```

2. **启动后端服务**

   参考后端项目 [README.md](https://gitee.com/youlaiorg/youlai-boot#%E9%A1%B9%E7%9B%AE%E8%BF%90%E8%A1%8C) 完成本地启动

3. **修改前端配置**

   编辑 `.env.development` 文件：

   ```bash
   # 将线上地址替换为本地地址
   VITE_APP_API_URL = 'http://localhost:8989'
   ```

### Mock 数据

项目支持 Mock 数据模式（v2.5.0+）：

```bash
# 修改 .env.development
VITE_APP_API_URL = 'http://localhost:3000'
```

## 📦 项目部署

### 构建生产包

```bash
# 生产环境打包
pnpm run build:prod
```

### Nginx 部署

1. **上传文件**：将 `dist` 目录下的文件上传至服务器 `/usr/share/nginx/html` 目录

2. **配置 Nginx**：编辑 `nginx.conf`

```nginx
server {
    listen       80;
    server_name  localhost;

    # 前端静态资源
    location / {
        root   /usr/share/nginx/html;
        index  index.html index.htm;
        try_files $uri $uri/ /index.html; # 解决 Vue Router history 模式 404 问题
    }

    # 反向代理后端 API
    location /prod-api/ {
        proxy_pass http://api.experiment.ncepu.edu.cn/;  # 替换为你的后端 API 地址
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}
```

3. **重启 Nginx**

```bash
nginx -s reload
```

## 📝 代码规范

### Git 提交规范

项目使用 Commitizen 规范化 Git 提交：

```bash
# 使用交互式提交（推荐）
pnpm run commit
```

![Git提交规范](https://foruda.gitee.com/images/1687755823165218215/c1705416_716974.png)

**提交类型说明**：

| 类型 | 说明 |
| :--: | :--: |
| `feat` | 新功能 |
| `fix` | 修复 Bug |
| `docs` | 文档更新 |
| `style` | 代码格式调整（不影响功能） |
| `refactor` | 代码重构 |
| `perf` | 性能优化 |
| `test` | 测试相关 |
| `chore` | 构建/工具链相关 |

### 代码检查

```bash
# ESLint 检查并修复
pnpm run lint:eslint

# Prettier 格式化
pnpm run lint:prettier

# Stylelint 样式检查
pnpm run lint:stylelint
```

### Git Hooks

项目配置了 Husky，在提交前自动执行：

- ✅ 代码格式化
- ✅ 代码质量检查
- ✅ 提交信息验证

## 📚 技术文档

### 系列教程

- [基于 Vue3 + Vite4 + TypeScript + Element-Plus 从0到1搭建后台管理系统](https://blog.csdn.net/u013737132/article/details/130191394)
- [ESLint + Prettier + Stylelint + EditorConfig 约束和统一前端代码规范](https://blog.csdn.net/u013737132/article/details/130190788)
- [Husky + Lint-staged + Commitlint + Commitizen + cz-git 配置 Git 提交规范](https://blog.csdn.net/u013737132/article/details/130191363)

### 技术栈文档

- [Vue 3 官方文档](https://cn.vuejs.org/)
- [Vite 官方文档](https://cn.vitejs.dev/)
- [Element Plus 文档](https://element-plus.org/zh-CN/)
- [Pinia 文档](https://pinia.vuejs.org/zh/)
- [TypeScript 文档](https://www.typescriptlang.org/zh/)
- [Vue Router 文档](https://router.vuejs.org/zh/)
- [UnoCSS 文档](https://unocss.dev/)

## ❓ 常见问题

### 1. Sass 废弃警告

**问题**：启动时出现大量 `Deprecation Warning [legacy-js-api]` 警告

**解决**：✅ 已解决！项目已完成 Sass 编译器优化，使用 `sass-embedded` 现代编译器，无警告输出。

### 2. 组件类型声明问题

**问题**：添加新组件后出现类型错误

**解决**：

1. 临时开启 `vite.config.ts` 中的 `dts: true`
2. 等待类型文件生成
3. 再次设置为 `dts: false`

### 3. 浏览器访问空白

**问题**：项目启动后浏览器显示空白页

**解决**：升级浏览器版本，低版本浏览器可能不支持某些 ES6+ 语法（如可选链操作符 `?.`）

### 4. 项目更新后问题

**问题**：同步仓库更新后出现各种错误

**解决**：

```bash
# 清除依赖重新安装
rm -rf node_modules pnpm-lock.yaml
pnpm install

# 清除 Vite 缓存
rm -rf node_modules/.vite
```

### 5. 组件、函数引用爆红

**问题**：VSCode 中组件或函数显示类型错误

**解决**：重启 VSCode

## 📄 许可证

本项目采用 [MIT](LICENSE) 许可证

## 🙏 致谢

本项目基于 [vue3-element-admin](https://gitee.com/youlaiorg/vue3-element-admin) 开发，感谢原作者的开源贡献。

---

**最后更新**：2024年11月