# Vue3 Admin 前端脚手架

**Repository Path**: darkwinoom/vue3-admin-scaffold

## Basic Information

- **Project Name**: Vue3 Admin 前端脚手架
- **Description**: 这是一个使用 vue3 + typescript + element plus 搭建的示例，包含完整登录与鉴权功能，可用于PC端项目后台管理。
- **Primary Language**: TypeScript
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 1
- **Created**: 2024-09-22
- **Last Updated**: 2025-08-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: TypeScript, vue3, Element-UI, pure-admin

## README

# Vue3 Admin 前端脚手架

这是一个使用 vue3 + typescript + element plus 搭建的示例，包含完整登录与鉴权功能，可用于PC端项目后台管理。

![登录界面](./docs/login.png)

![内部界面](./docs/inner.png)

## 特色功能

- 引入 PlusProComponents 组件，提高常规增删改查页面构建效率；
- 引入 NaiveUI 与 ElementPlus 共存，PlusProComponents、ElementPlus、NaiveUI 自动按需引入；
- 优化统一配置目录 `src/config`，最大差异化配置，移除配置全局缓存，增加包括 UI 库主题样式配置；
- 本项目可独立使用 `mock` 运行，也可搭配项目 [tp8-server-scaffold](https://gitee.com/darkwinoom/tp8-server-scaffold) 作为其后端一同使用；

## Electron 版本

[点击前往查看](https://gitee.com/darkwinoom/vue3-admin-electron-scaffold)

## 依赖说明

本脚手架基于 [pure-admin-thin](https://github.com/pure-admin/pure-admin-thin)，目前已同步版本6.0.0。

在保留原版核心功能的前提下，优化了部分依赖的使用，删除了部分占比较大的功能（精简了约一半的原体积），同时调整了配置项存储方式（后续会同步官方更新）。

本项目接入了 [NaiveUI](https://www.naiveui.com/zh-CN/os-theme)，这是一个轻量化的组件库，可与原有的 [ElementPlus](https://element-plus.org/zh-CN/) 一起使用。

## 在线预览

[点击访问](https://vue3-admin-scaffold.netlify.app/)

## 技术栈

- vue3 + vite6 + typescript
- vue-router4 + pinia
- element-plus + naive-ui
- axios
- tailwindcss + sass

## 安装使用

```sh
pnpm install
```

### 本地运行

```sh
pnpm dev
```

本地运行成功后可访问 <http://localhost:8848/>，端口号可在 `.env` 文件中修改

### 项目打包

您可以通过运行打包命令 `pnpm build` 生成文件，打包后文件将会自动生成至 `/dist` 文件夹中。

打包命令可通过配置文件 `.env.production` 进行配置，修改后重新执行打包命令即可。

此外为了方便多平台运行需求，减少来回配置负担，本项目可进行预发布打包，命令如下：

```sh
pnpm build:staging
```

预发布打包配置文件 `.env.staging`，除此之外与常规打包一致

### 打包预览

本项目内置预览命令 `pnpm preview`，该命令会自动运行上一个打包文件（端口与 `.env` 中配置一致），方便您进行预览。

此外，如果您使用 `vscode` 进行开发，推荐使用插件 `Live Server` 进行预览。本项目已配置了 `Live Server` 基本信息，您可以直接启动服务使用。

### 打包分析

您可以通过以下命令进行打包分析：

```sh
pnpm report
```

运行后会先执行一次打包操作，然后在根目录生成 report.html 报告文件

### 其它命令

_其它支持的命令可通过查看 `package.json` 文件确认_

## 项目说明

### 图标

项目内置了 `iconify` 作为图标库，该图标库拥有万余开源矢量图标，省去开发中图标难选择的问题。仅需要通过以下代码即可使用：

```vue
<script setup lang="ts">
import UserIcon from "~icons/ep/user";
</script>

<template>
  <IconifyIconOffline :icon="UserIcon" />
</template>
```

您也可以通过设置字符串的形式自动选用在线图标。例如上述 `UserIcon`，可通过传入 `ep:user` 即可识别图标。使用方法如下：

```vue
<IconifyIconOnline icon="ep:user" />
```

考虑到非公网环境下使用图标的情况，您可以通过将其添加到配置 `/src/config/icons.ts` 中，即可在离线使用 `IconifyIconOffline` 图标（此方法已适配菜单中的图标配置）。

访问 [iconify 官方](https://icon-sets.iconify.design) 查看可用图标（需要注意图标版本是否与本地版本适配）。

### 目录结构

```md
├─ build 构建工具
├─ mock mock目录
├─ public WEB目录（打包时移动到根目录）
├─ src 开发目录
│ ├─ api 请求接口
│ ├─ assets 静态资源
│ ├─ components 全局组件
│ ├─ config 全局配置
│ ├─ directives 全局指令
│ ├─ layout 核心布局
│ ├─ plugins 全局插件
│ ├─ router 路由配置
│ ├─ store 状态管理
│ ├─ style 全局样式
│ ├─ utils 全局工具
│ ├─ view 页面视图
│ ├─ App.vue 入口页面
│ ├─ main.ts 入口文件
├─types 全局类型配置
│  
├─ .env 环境变量配置
├─ .env.development 环境变量配置（开发模式）
├─ .env.staging 环境变量配置（预发布模式）
├─ .env.production 环境变量配置（生产模式）
├─ ...... 其它配置文件（如：package.json、tsconfig.json等）
```

更多目录说明可以参考 [pure-admin目录结构](https://pure-admin.cn/pages/directory/)。

### 开发规范

以下规范个人开发遵循，以供参考：

- 对于自动引入的组件使用全小写 + "-" 形式使用（如：`<el-text/>`，而非 `<ElText/>`），对于手动引入的组件使用大驼峰命名；
- 样式 class 使用全小写 + "-" 的形式书写，使用 scoped 标签定义 vue 页面中的样式；
- 使用了监听事件（如：window.addEventListener）的页面需要在 onBeforeUnmount 中将其移除（如：window.removeEventListener）；
- 开发时善用浏览器 F12 工具，保证并及时处理代码运行时产生的 warning 和 error。同时善用编辑器 eslint 工具，确保代码规范；
- 推荐使用 vscode 进行开发，并安装 `./.vscode/extensions.json` 中的推荐依赖（联网时首次打开会提示并自动安装）；

## 项目配置

### 环境配置

环境配置位于项目根目录，以 `.env` 开头，适配不同运行环境。项目内置环境如下：

- `.env` 对所有环境配置生效
- `.env-development` 对开发 `pnpm dev` 模式生效
- `.env-production` 对打包 `pnpm build` 模式生效
- `.env-staging` 对预发布 `pnpm build:staging` 模式生效

完整配置信息如下：

```bash
# 平台本地运行端口号（适用开发模式和预览）
VITE_PORT = 8848

# 是否隐藏首页 隐藏 true 不隐藏 false （勿删除，VITE_HIDE_HOME只需在.env文件配置）
VITE_HIDE_HOME = false

# 开发环境读取配置文件路径 & 线上环境平台打包路径
VITE_PUBLIC_PATH = /

# 路由历史模式
# Hash模式传"hash"、HTML5模式传"h5"、Hash模式带base参数传"hash,base参数"、HTML5模式带base参数传"h5,base参数"
VITE_ROUTER_HISTORY = "hash"

# 是否在打包时使用cdn替换本地库 替换 true 不替换 false
VITE_CDN = false

# 是否启用gzip压缩或brotli压缩（分两种情况，删除原始文件和不删除原始文件）
# 压缩时不删除原始文件的配置：gzip、brotli、both（同时开启 gzip 与 brotli 压缩）、none（不开启压缩，默认）
# 压缩时删除原始文件的配置：gzip-clear、brotli-clear、both-clear（同时开启 gzip 与 brotli 压缩）、none（不开启压缩，默认）
VITE_COMPRESSION = "none"

# 常规API服务器地址，使用内部工具 http.request 请求时会作为 baseURL
VITE_BASE_API = http://localhost:8100/api/admin

# 可自定义其它API，遵循 VITE_[名称]_API 即可。例如：
# VITE_UC_API = http://YOUR_ADDRESS/api
#
# 可直接调用：
# ------------------------------------------------------------------
# import { http } from '@/utils/http'
# http.request<HttpResponse>('POST', 'address/center', { data }, { baseAPI: 'uc' })
# 实际请求：http://YOUR_ADDRESS/api/address/center
# ------------------------------------------------------------------
# 查看 /src/config/index.ts 中 appConfig.request.url 了解实现细节

# 是否启用本地mock（支持打包模式）
VITE_USE_MOCK = true

# 动态配置覆写地址（未配置不启用）
# 可配置本服务器或远程服务器地址，在生产模式下慎用（可能会存在安全隐患）
# 查看 /src/config/index.ts 中 siteConfig 了解可复写配置
VITE_ASYNC_CONFIG_URL = /platform-config.json
```

#### 内部配置

配置文件位于 `./src/config` 中：

| 配置文件         | 描述说明                               |
| ---------------- | -------------------------------------- |
| element-var.scss | ElementPlus 主题样式配置               |
| icons.ts         | 菜单管理可选图标配置（不影响实际应用） |
| index.ts         | 系统配置，包含可外部配置与内部配置     |
| naive-var.ts     | NaiveUI 主题样式配置                   |
| theme.scss       | 主题颜色方案配置，对应配置项 Theme     |

系统配置说明可参考 `/src/config/type.d.ts` 中 `AppConfig` 注释。

#### 外部配置

配置文件位于 `./public/platform-config.json` 中，可复写 `./src/config/index.ts` 中的 `siteConfig` 配置。

需要开启 `.env` 中 `VITE_OPEN_ASYNC_CONFIG` 才会生效。

### 路由定义

路由可在 `/src/router/modules` 中进行定义，也可通过后端 api 动态获取路由（可查看 getAsyncRoutes 相关示例）。

## 精简说明

- 将 ElementPlus 从全量引入改成按需引入；
- 移除全局变量缓存；
- 完整移除菜单搜索、系统配置面板相关功能；
- 重构登录认证部分功能，调整如下：
  - 移除头像，新增 uid、phone、email、remark；
  - 优化后端 expires，现支持所有时间格式（包括时间戳）；
  - 将原 token cookie 存储转移到 localStorage 中；
  - 优化拆分设置 token 和设置用户信息流程（方便刷新用户信息）；
  - 增加 token 刷新认证失败提醒并跳转登录页功能；
- 删除不必要的依赖、组件、指令等功能，简化部分复杂页面整体流程；

## 开发方向

- [x] 接入个人项目后端（tp8-serverscaffold）
- [x] 适配暗黑模式
- [x] 使用离线图标替换在线图标（在线图标功能依然支持）
- [ ] 接入 chat-ai
- [ ] 接入 vitest 和 playwright
- [ ] 接入微前端

待加入...

## Git 提交规范

- feat 增加新的业务功能
- fix 修复业务问题/BUG
- perf 优化性能
- style 更改代码风格, 不影响运行结果
- refactor 重构代码
- revert 撤销更改
- test 测试相关, 不涉及业务代码的更改
- docs 文档和注释相关
- chore 更新依赖/修改脚手架配置等琐事
- workflow 工作流改进
- ci 持续集成相关
- types 类型定义文件更改
- wip 开发中

## 开发环境

> 本项目可运行于 node > 20 的环境中，pnpm 推荐使用 10 及以上版本

以下为个人开发环境参考：

- pnpm v10.12.3
- node v22.17.0
- npm v10.9.2

## 附：参考文档

- [PureAdmin官方文档](https://pure-admin.cn/pages/introduction)
- [PlusProComponents官方文档](https://plus-pro-components.com/)
- [@pureadmin/utils常用工具函数文档](https://pure-admin-utils.netlify.app/)
- [ElementPlus官方文档](https://element-plus.org/zh-CN)
- [NaiveUI官方文档](https://www.naiveui.com/zh-CN/os-theme)