Vben Admin新手教程：从零开始构建Vue3后台系统

前言：开启你的Vue3后台之旅

在当今前端技术栈日益更新迭代的浪潮中，Vue3以其卓越的性能、Composition API的强大表现力以及TypeScript的完美支持，已成为构建现代Web应用的首选框架之一。而对于需要快速搭建高质量、企业级后台管理系统的开发者而言，选择一个成熟、稳定且功能强大的后台管理模板，无疑能事半功倍。

Vben Admin，正是在这样的背景下应运而生并脱颖而出的一颗璀璨明星。它基于Vue3、Vite、TypeScript、Ant Design Vue等前沿技术栈构建，提供了一整套开箱即用的解决方案，从基础布局、路由权限、状态管理到国际化、主题切换，乃至各种复杂组件的封装，都为开发者考虑得周到而详尽。

本教程旨在为Vue3新手和希望快速上手Vben Admin的开发者提供一份“从零开始”的详尽指南。我们将一步步深入探索Vben Admin的核心理念、项目结构、关键功能以及如何在此基础上构建你自己的Vue3后台系统。无论你是前端初学者，还是希望提升开发效率的资深工程师，相信这份教程都能为你带来实实在在的帮助。

准备好了吗？让我们一起踏上这场充满挑战与乐趣的Vue3后台系统构建之旅！

第一章：准备工作与快速启动

在正式开始之前，我们需要确保开发环境已正确配置。

1.1 开发环境准备

Node.js: 确保你的系统安装了Node.js，推荐使用LTS（长期支持）版本，例如16.x或18.x。你可以通过在终端输入 node -v 和 npm -v 来检查版本。如果没有安装，请访问Node.js官网下载并安装。
包管理器: Vben Admin推荐使用pnpm，它在性能和磁盘空间利用上优于npm和yarn。如果你尚未安装pnpm，可以通过 npm install -g pnpm 进行全局安装。当然，使用npm或yarn也是可以的，但本教程将以pnpm为例。
Git: 项目的克隆需要Git工具。请确保你的系统已安装Git。
IDE: 推荐使用Visual Studio Code (VS Code)，并安装一些必要的插件，如Volar (Vue 3官方推荐的IDE支持，替代Vetur)、ESLint、Prettier等，它们能极大提升开发体验和代码质量。

1.2 克隆项目与安装依赖

Vben Admin的项目源码托管在GitHub上，我们可以通过Git将其克隆到本地。

克隆仓库: 打开你的终端或命令行工具，选择一个合适的目录，然后执行以下命令：
bash git clone https://github.com/vbenjs/vben-admin.git cd vben-admin
这会将Vben Admin的最新代码克隆到名为 vben-admin 的文件夹中，并切换到该目录。
安装依赖: 进入项目目录后，使用你选择的包管理器安装所有项目依赖。
“`bash
# 推荐使用 pnpm
pnpm install

如果你更喜欢 npm

npm install

如果你使用 yarn

yarn install

“`
这个过程可能需要一些时间，取决于你的网络速度和机器性能。
启动开发服务器: 依赖安装完成后，我们可以启动开发服务器，预览项目。
“`bash
# 推荐使用 pnpm
pnpm dev

如果你更喜欢 npm

npm run dev

如果你使用 yarn

yarn dev

`` 执行成功后，通常会在终端显示一个本地开发服务器的地址，例如http://localhost:3100`。在浏览器中打开这个地址，你将看到Vben Admin的登录页面。

恭喜你！你已经成功启动了Vben Admin项目。现在，是时候深入了解它的内部结构了。

第二章：深入理解项目结构与核心配置

一个清晰、合理的项目结构是高效开发的基础。Vben Admin在项目结构上做了精心设计，旨在提高可维护性和扩展性。

2.1 核心目录概览

在 vben-admin 项目的根目录下，你将看到以下一些关键目录和文件：

node_modules/: 项目依赖包的存放目录。
public/: 静态资源目录，不会被Vite处理，直接复制到构建输出目录。
src/: 核心源码目录，我们大部分的开发工作都将在这里进行。
.env* 文件: 环境变量配置文件（如 .env.development, .env.production），用于区分不同环境的配置。
index.html: 项目入口HTML文件。
package.json: 项目的元数据文件，包含项目名称、版本、依赖、脚本等信息。
tsconfig.json: TypeScript配置文件。
vite.config.ts: Vite的配置文件，Vben Admin的强大功能很多都在这里进行了定制。

2.2 `src` 目录详解

src 目录是Vben Admin的灵魂所在，它被划分为多个职责明确的子目录：

src/api/: 存放所有与后端接口交互的模块。通常按功能划分，如 user.ts, system.ts 等。
src/assets/: 存放静态资源，如图片、字体文件等。
src/components/: 存放全局可复用的Vue组件，例如BasicTable、BasicForm、CountTo等。这些组件通常是经过封装，具有更强大的功能和更好的复用性。
src/design/: 存放全局样式变量和通用样式文件，主要用于主题和UI的统一管理。
src/enums/: 存放枚举类型，如角色权限枚举、状态枚举等，提高代码可读性和可维护性。
src/hooks/: 存放可复用的组合式函数（Composition API），用于封装业务逻辑，提高逻辑复用性。例如 useMessage, useTabs 等。
src/layouts/: 定义了系统的整体布局结构，如侧边栏、顶部导航、内容区域等。
src/locales/: 国际化（i18n）配置文件，包含不同语言的翻译文本。
src/logics/: 存放一些业务逻辑文件，例如权限逻辑、锁屏逻辑等。
src/router/: 路由管理模块，包含路由配置、路由守卫等。
- src/router/routes/modules/: 存放按模块划分的路由配置，是核心路由定义的地方。
src/settings/: 存放项目级别的全局设置，如系统标题、网络请求超时时间、主题配置等。
src/store/: 状态管理模块，基于Pinia实现，存放各种全局状态。
src/styles/: 存放项目特定的样式文件，补充 src/design 中的全局样式。
src/utils/: 存放各种工具函数，如日期格式化、数据校验、本地存储操作等。
src/views/: 存放所有的页面级组件，通常与路由配置一一对应。
src/App.vue: 根组件。
src/main.ts: 项目入口文件，进行Vue应用的初始化、插件注册等。

通过这样的分层，Vben Admin实现了高度的模块化和解耦，使得项目结构清晰，易于理解和维护。

第三章：核心功能模块详解

Vben Admin之所以强大，在于它内置了众多企业级后台系统所需的核心功能。本章将对这些关键模块进行详细解析。

3.1 路由管理：动态与权限控制

Vben Admin的路由系统基于Vue Router 4，并进行了深度定制，实现了动态路由和精细化的权限控制。

路由配置:
- 静态路由: 定义在 src/router/routes/basic.ts 中，例如登录页、404页等，无需权限即可访问。
- 动态路由: 定义在 src/router/routes/modules/ 目录下的各个模块文件中。这些路由通常需要权限才能访问，并在用户登录后根据其角色权限动态生成。
- Meta配置: 每个路由对象都包含一个 meta 字段，用于配置额外信息：
  - title: 菜单名称，支持国际化。
  - icon: 菜单图标。
  - ignoreAuth: 是否忽略权限验证，true表示无需权限。
  - keepAlive: 是否缓存组件。
  - hideMenu: 是否在菜单中隐藏。
  - roles: 访问该路由所需的角色数组，例如 ['admin', 'editor']。
路由守卫: src/router/guard/permissionGuard.ts 文件是权限系统的核心。它在每次路由跳转时执行，根据用户的登录状态和角色权限，判断用户是否有权访问目标路由。
- 登录拦截: 未登录用户会被重定向到登录页。
- 权限判断: 已登录用户根据其角色和路由的 meta.roles 进行匹配，无权限则重定向到403页面。
- 动态添加路由: 在用户登录成功后，系统会根据用户权限动态生成并添加可访问的路由菜单。

3.2 状态管理：拥抱Pinia

Vben Admin全面拥抱了Pinia作为其状态管理库。Pinia是Vue官方推荐的状态管理库，相比Vuex更轻量、API更简洁、对TypeScript支持更友好。

Pinia Store结构: 所有的Store都定义在 src/store/modules/ 目录下，每个文件代表一个独立的模块Store。例如：
- app.ts: 存储应用全局设置，如主题、语言、侧边栏状态等。
- user.ts: 存储用户信息，如用户ID、姓名、头像、角色、权限列表等。
- permission.ts: 存储权限相关信息，如动态路由、菜单列表等。
定义Store: 每个Store通过 defineStore 函数定义，包含 state、getters 和 actions。
“`typescript
// src/store/modules/user.ts 示例
import { defineStore } from ‘pinia’;
import { store } from ‘/@/store’;

export const useUserStore = defineStore({
id: ‘app-user’,
state: () => ({
token: undefined,
userInfo: null,
roleList: [],
}),
getters: {
getToken(): string | undefined {
return this.token;
},
getUserInfo(): Nullable {
return this.userInfo;
},
},
actions: {
setToken(token: string | undefined) {
this.token = token;
},
setUserInfo(info: UserInfo | null) {
this.userInfo = info;
},
// … 其他操作，如登录、登出
},
});

// 在组件中使用
// const userStore = useUserStore();
// userStore.setToken(‘your_token’);
`` * **使用Store**: 在Vue组件中，你可以通过const store = useXXXStore()` 钩子函数来获取并操作对应的Store。

3.3 权限系统：精细化控制

权限系统是后台管理的核心之一，Vben Admin提供了完善的基于角色的权限控制（RBAC）方案。

登录流程:
1. 用户提交账号密码。
2. 后端验证通过后返回用户Token、用户信息和角色列表。
3. 前端将这些信息存储在Pinia Store和本地存储中。
4. 根据用户的角色列表，动态生成并加载可访问的路由和菜单。
页面权限: 通过路由守卫 (permissionGuard.ts) 和路由的 meta.roles 字段实现。没有相应角色的用户无法访问对应页面。
按钮/元素权限: Vben Admin提供了一个 v-auth 自定义指令，用于控制页面内按钮或其他元素的显示与隐藏。
“`html

删除

新增用户
``v-auth` 指令会根据当前用户的权限列表判断是否渲染或隐藏元素。这种细粒度的权限控制非常适合企业级应用。

3.4 UI组件库：Ant Design Vue

Vben Admin选择了Ant Design Vue作为其UI组件库。Ant Design Vue是一个高质量、企业级的Vue UI组件库，提供了丰富的组件和优秀的用户体验。

按需加载: Vben Admin通过Vite的配置，实现了Ant Design Vue的按需加载，有效减少了打包体积。
组件使用: 你可以直接在Vue组件中引入并使用Ant Design Vue的各种组件，例如 <a-button>, <a-table>, <a-form> 等。
二次封装: Vben Admin在 src/components/ 目录下对一些常用组件进行了二次封装，如 BasicTable（高级表格）、BasicForm（高级表单）、Description（详情组件）等。这些封装组件通常集成了常用功能和最佳实践，极大提升了开发效率。例如，BasicTable 可能内置了分页、搜索、行选择等功能，并提供了更简洁的API。

3.5 网络请求：Axios封装

Vben Admin对Axios进行了高度封装，提供了一套统一且强大的网络请求方案。

封装位置: 主要代码位于 src/utils/http/axios/ 目录下。
拦截器:
- 请求拦截器: 统一处理请求头（例如添加Token）、参数转换、加载动画等。
- 响应拦截器: 统一处理响应数据、错误信息（例如Token过期、权限不足）、关闭加载动画等。
API模块化: src/api/ 目录下按照功能模块划分了API文件。每个API文件定义了与后端对应模块的接口请求函数。
“`typescript
// src/api/sys/user.ts 示例
import { defHttp } from ‘/@/utils/http/axios’;

enum Api {
Login = ‘/login’,
GetUserInfo = ‘/getUserInfo’,
}

/*
* @description: 用户登录
/
export function loginApi(params: LoginParams) {
return defHttp.post({
url: Api.Login,
params,
});
}

/*
* @description: 获取用户信息
/
export function getUserInfoApi() {
return defHttp.get({ url: Api.GetUserInfo }, { errorMessageMode: ‘none’ });
}
`` * **使用方式**: 你只需在组件中导入src/api` 下定义的接口函数即可发起请求，无需关心底层的Axios配置和错误处理，这大大简化了API调用。

3.6 主题与国际化：个性化与全球化

主题定制: Vben Admin支持主题定制和动态切换。
- Less变量: Ant Design Vue本身支持通过Less变量进行主题定制。Vben Admin在 src/design/index.less 和 src/design/var/ 中定义了大量 Less 变量，可以修改这些变量来调整主题颜色、字体、间距等。
- 动态主题: Vben Admin还提供了在运行时切换主题的能力（例如亮色/暗色模式，或自定义主题色），通常在系统设置页面提供入口。
国际化 (i18n):
- Vue I18n: Vben Admin集成了Vue I18n，支持多语言切换。
- 语言文件: src/locales/ 目录下存放不同语言的JSON格式翻译文件，如 zh-CN.json、en.json。
- 使用方式: 在模板中使用 $t('message.key')，在JavaScript代码中使用 t('message.key') 来获取翻译文本。语言切换逻辑通常在 src/store/modules/app.ts 中管理，并提供切换入口。

第四章：开发实践与最佳实践

掌握了核心功能，接下来我们将探讨如何在Vben Admin的基础上进行日常开发，并遵循一些最佳实践。

4.1 新增一个页面模块

假设我们要新增一个“用户管理”页面：

定义路由:
- 在 src/router/routes/modules/ 目录下创建一个 user.ts 文件。
- 定义一个路由对象，包含 path, name, component, meta 等字段。component 通常指向 LAYOUT 布局组件，并在 children 中定义实际页面的路由。
  “`typescript
  // src/router/routes/modules/user.ts
  import { LAYOUT } from ‘/@/router/constant’;
  import { AppRouteModule } from ‘/@/router/types’;
const user: AppRouteModule = {
path: ‘/user’,
name: ‘User’,
component: LAYOUT,
redirect: ‘/user/list’,
meta: {
title: ‘用户管理’, // 菜单名称
icon: ‘ant-design:user-outlined’, // 菜单图标
orderNo: 10, // 菜单排序
},
children: [
{
path: ‘list’,
name: ‘UserList’,
component: () => import(‘/@/views/sys/user/index.vue’), // 实际页面组件路径
meta: {
title: ‘用户列表’,
roles: [‘admin’, ‘user:view’], // 需要的权限
keepAlive: true,
},
},
// … 其他用户相关页面，如用户详情、角色管理等
],
};

export default user;
2. **创建页面组件**: * 在 `src/views/sys/` 目录下创建一个 `user` 文件夹。 * 在 `user` 文件夹下创建 `index.vue` 文件，这将是你的用户列表页面。vue

`` 3. **定义API**: * 在src/api/sys/目录下创建user.ts文件。 * 定义与用户管理相关的接口函数。 4. **定义数据**: * 在src/views/sys/user/目录下创建user.data.ts文件。 * 定义表格的columns和搜索表单的searchFormSchema` 配置。

4.2 封装可复用组件和Hooks

组件封装: 如果你发现多个页面有相似的UI或功能逻辑，可以考虑将其封装成组件，放在 src/components/ 目录下。例如，一个通用的图片上传组件、一个Markdown编辑器组件等。
Hooks封装: 对于一些可复用的逻辑，如数据加载、表单提交、弹窗管理等，可以使用Composition API的ref, reactive, computed, watch等，封装成自定义Hooks，放在 src/hooks/ 目录下。例如，Vben Admin就提供了 useMessage、useModal 等非常实用的Hooks。

4.3 环境变量与配置

Vben Admin通过Vite和.env文件管理环境变量。

.env文件:
- .env: 默认环境变量。
- .env.development: 开发环境特有变量。
- .env.production: 生产环境特有变量。
- 所有以 VITE_ 开头的变量都会通过 import.meta.env 暴露给前端代码。
  “`properties
.env.development 示例

VITE_GLOB_APP_TITLE = Vben Admin 开发版
VITE_GLOB_API_URL = /api # 开发环境接口代理前缀
“`
src/settings/: 存放全局项目配置。
- projectSetting.ts: 项目基本配置，如是否显示面包屑、是否开启KeepAlive等。
- designSetting.ts: 主题和UI相关配置。
- globSetting.ts: 全局变量配置，可以通过 getGlobSetting() 函数获取。

4.4 代码规范与工具

Vben Admin集成了ESLint和Prettier，帮助团队维护统一的代码风格和质量。

ESLint: 代码静态分析工具，发现潜在问题和不规范代码。
Prettier: 代码格式化工具，自动统一代码风格。
Git Hooks: 通常项目会配置Git Hooks（例如使用husky），在提交代码前自动运行ESLint和Prettier，确保提交的代码符合规范。

第五章：构建与部署

当你的系统开发完成后，需要将其构建为生产环境可用的静态文件并进行部署。

5.1 构建项目

使用以下命令进行项目构建：

“`bash

如果你更喜欢 npm

npm run build

如果你使用 yarn

yarn build

“`

执行成功后，会在项目根目录下生成一个 dist 文件夹。这个文件夹包含了所有用于生产环境的静态文件（HTML, CSS, JavaScript, 图片等），这些文件都经过了优化（压缩、代码分割、Tree Shaking等）。

5.2 部署

dist 文件夹中的内容是纯静态文件，你可以将其部署到任何支持静态文件服务的Web服务器上，例如：

Nginx: 最常用的生产环境Web服务器。配置Nginx指向 dist 目录即可。
Apache: 类似的Web服务器，通过配置虚拟主机实现。
CDN: 如果项目对访问速度有较高要求，可以将静态资源上传到CDN服务商。
云存储: 如阿里云OSS、腾讯云COS等，配合CDN使用。
Docker: 将应用打包成Docker镜像，方便部署和管理。

Nginx部署示例配置 (简化版):

“`nginx
server {
listen 80;
server_name your_domain.com; # 替换为你的域名或IP

location / {
    root   /path/to/vben-admin/dist; # 替换为你的dist目录的绝对路径
    index  index.html index.htm;
    try_files $uri $uri/ /index.html; # 处理单页应用路由刷新问题
}

# 代理后端API请求，避免跨域
location /api/ {
    proxy_pass http://your_backend_server:port/; # 替换为你的后端服务地址
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

error_page   500 502 503 504  /50x.html;
location = /50x.html {
    root   html;
}

}
`` **注意：** 部署时务必处理好后端API的**跨域问题**。在开发环境，Vben Admin的vite.config.ts中通常会配置proxy来解决。在生产环境，通常通过Nginx等服务器的反向代理来解决，如上述Nginx配置中的/api/` 代理。

总结与展望

通过本教程的详细学习，你已经对Vben Admin这个基于Vue3、Vite和TypeScript的强大后台管理系统模板有了全面而深入的了解。我们从环境准备和快速启动开始，逐步剖析了其精心设计的项目结构、深入探讨了路由、状态管理、权限、UI组件、网络请求、主题和国际化等核心功能模块，并提供了日常开发和部署的最佳实践。

Vben Admin的出现，极大地降低了构建高质量企业级后台管理系统的门槛，让开发者能够将更多精力投入到业务逻辑的实现上，而非基础框架的搭建与功能开发。

现在，你已经：
* 成功搭建并运行了Vben Admin项目。
* 理解了其清晰的项目目录结构。
* 掌握了路由管理、Pinia状态、强大的权限系统。
* 熟悉了Ant Design Vue组件和Axios网络请求的封装。
* 了解了主题切换和国际化配置。
* 学会了如何新增页面模块和封装组件/Hooks。
* 掌握了项目的构建与部署流程。

接下来的学习和实践建议：
1. 深入阅读官方文档: Vben Admin的官方文档（虽然目前主要为中文）非常详尽，是进一步学习和解决问题的宝库。
2. 动手实践: 尝试修改现有页面、新增复杂功能模块、对接真实后端API，将所学知识付诸实践。
3. 探索更多高级特性: 如表格高级筛选、表单动态渲染、图表集成、数据可视化等。
4. 参与社区: 关注Vben Admin的GitHub仓库，参与issue讨论或贡献代码，与其他开发者交流学习。

Vben Admin不仅仅是一个模板，更是一套成熟的前端工程化解决方案。希望这份教程能成为你驾驭Vben Admin，构建卓越Vue3后台系统的坚实基石。祝你在前端开发的道路上越走越远，创造出更多优秀的作品！

Vben Admin新手教程：从零开始构建Vue3后台系统 – wiki基地

Vben Admin新手教程：从零开始构建Vue3后台系统

前言：开启你的Vue3后台之旅

第一章：准备工作与快速启动

1.1 开发环境准备

1.2 克隆项目与安装依赖

如果你更喜欢 npm

npm install

如果你使用 yarn

yarn install

如果你更喜欢 npm

npm run dev

如果你使用 yarn

yarn dev

第二章：深入理解项目结构与核心配置

2.1 核心目录概览

2.2 `src` 目录详解

第三章：核心功能模块详解

3.1 路由管理：动态与权限控制

3.2 状态管理：拥抱Pinia

3.3 权限系统：精细化控制

3.4 UI组件库：Ant Design Vue

3.5 网络请求：Axios封装

3.6 主题与国际化：个性化与全球化

第四章：开发实践与最佳实践

4.1 新增一个页面模块

4.2 封装可复用组件和Hooks

4.3 环境变量与配置

.env.development 示例

4.4 代码规范与工具

第五章：构建与部署

5.1 构建项目

推荐使用 pnpm

如果你更喜欢 npm

npm run build

如果你使用 yarn

yarn build

5.2 部署

总结与展望

发表评论取消回复

Vben Admin新手教程：从零开始构建Vue3后台系统

前言：开启你的Vue3后台之旅

第一章：准备工作与快速启动

1.1 开发环境准备

1.2 克隆项目与安装依赖

如果你更喜欢 npm

npm install

如果你使用 yarn

yarn install

如果你更喜欢 npm

npm run dev

如果你使用 yarn

yarn dev

第二章：深入理解项目结构与核心配置

2.1 核心目录概览

2.2 src 目录详解

第三章：核心功能模块详解

3.1 路由管理：动态与权限控制

3.2 状态管理：拥抱Pinia

3.3 权限系统：精细化控制

3.4 UI组件库：Ant Design Vue

3.5 网络请求：Axios封装

3.6 主题与国际化：个性化与全球化

第四章：开发实践与最佳实践

4.1 新增一个页面模块

4.2 封装可复用组件和Hooks

4.3 环境变量与配置

.env.development 示例

4.4 代码规范与工具

第五章：构建与部署

5.1 构建项目

推荐使用 pnpm

如果你更喜欢 npm

npm run build

如果你使用 yarn

yarn build

5.2 部署

总结与展望

发表评论 取消回复

2.2 `src` 目录详解

发表评论取消回复