快速开始

5 分钟快速启动 Vben Admin 框架。

前置要求

环境要求

• Node.js >= 18.0
• pnpm >= 8.0
• Java >= 17
• Maven >= 3.8
• MySQL >= 5.7
• Redis >= 6.0

后端启动

1. 数据库初始化

# 进入 SQL 文件目录
cd vben-boot/sql

# 执行 SQL 脚本
# 使用 MySQL 客户端执行以下文件：
# - common_vben_sql.sql (核心表)
# - sys_region.sql (地区数据)

提示

可以使用 Navicat、DBeaver 等数据库工具导入 SQL 文件。

2. 配置文件

编辑 vben-boot/vben-admin/src/main/resources/application.yml：

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/vben_admin?useUnicode=true&characterEncoding=utf-8
    username: root
    password: your_password
  
  redis:
    host: localhost
    port: 6379
    password: # Redis 密码，如果没有可留空
    database: 0

# Sa-Token 配置
sa-token:
  token-name: Authorization
  timeout: 2592000
  activity-timeout: -1
  is-concurrent: true
  is-share: true
  token-style: uuid

3. 启动后端

Maven

cd vben-boot/vben-admin
mvn spring-boot:run

IDE

# 使用 IDEA 或 Eclipse
# 直接运行 VbenApplication.java

启动成功后，访问：

• API 文档：http://localhost:8080/swagger-ui.html
• 健康检查：http://localhost:8080/actuator/health

前端启动

1. 安装依赖

cd vue-vben-admin

# 安装 pnpm（如果未安装）
npm i -g corepack
corepack enable

# 安装项目依赖
pnpm install

依赖安装

如果需要安装额外的工具类依赖：

pnpm add -w xlsx crypto-js qrcode echarts viewerjs pdfjs-dist quill marked monaco-editor

2. 环境配置

编辑 vue-vben-admin/apps/web-antd/.env.development：

# API 地址
VITE_API_URL=http://localhost:8080

# 应用名称
VITE_APP_TITLE=Vben Admin

# 应用描述
VITE_APP_DESC=企业级管理系统框架

# 是否开启 Mock
VITE_USE_MOCK=false

3. 启动前端

# 启动开发服务器
pnpm dev

# 或指定应用启动
pnpm dev:antd   # Ant Design 版本
pnpm dev:ele    # Element Plus 版本
pnpm dev:naive  # Naive UI 版本

启动成功后，访问：http://localhost:5173

登录测试

默认账号

账号	密码	权限	说明
admin	123456	超级管理员	拥有所有权限
user	123456	普通用户	基础权限

登录步骤

1. 打开浏览器访问 http://localhost:5173
2. 输入账号：admin
3. 输入密码：123456
4. 点击登录按钮
5. 进入管理系统首页

首次登录

首次登录可能需要等待几秒钟，系统会初始化用户权限和菜单。

验证安装

后端验证

# 查看 Swagger API 文档
curl http://localhost:8080/swagger-ui.html

# 测试登录接口
curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"123456"}'

# 测试健康检查
curl http://localhost:8080/actuator/health

前端验证

打开浏览器开发者工具（F12）：

1. Console 标签 - 检查是否有错误信息
2. Network 标签 - 检查 API 请求是否正常
3. Application 标签 - 检查 Token 是否存储成功

项目构建

前端构建

# 构建生产环境
pnpm build

# 构建并分析包大小
pnpm build:analyze

# 预览构建结果
pnpm preview

构建产物位于 apps/web-antd/dist 目录。

后端构建

# Maven 打包
cd vben-boot
mvn clean package -DskipTests

# 运行 JAR 包
java -jar vben-admin/target/vben-admin.jar

常见问题

后端启动失败

数据库连接失败

问题： Communications link failure

解决：

1. 检查 MySQL 是否运行
2. 检查数据库名和密码是否正确
3. 检查防火墙是否阻止连接

Redis 连接失败

问题： Unable to connect to Redis

解决：

1. 检查 Redis 是否运行
2. 检查端口是否正确（默认 6379）
3. 检查密码配置

前端启动失败

依赖安装失败

问题： ENOENT: no such file or directory

解决：

# 清除缓存
rm -rf node_modules pnpm-lock.yaml
pnpm store prune

# 重新安装
pnpm install

端口被占用

问题： Port 5173 is already in use

解决： 修改 vite.config.mts 中的端口：

export default defineConfig({
  server: {
    port: 5174, // 修改为其他端口
  }
})

登录失败

账号密码错误

问题： 用户名或密码错误

解决：

1. 检查数据库中的用户表数据
2. 确认密码是否正确（默认：123456）
3. 检查用户状态是否启用

CORS 错误

问题： Access to XMLHttpRequest has been blocked by CORS policy

解决： 检查后端 CORS 配置：

@Configuration
public class CorsConfig {
    @Bean
    public CorsFilter corsFilter() {
        CorsConfiguration config = new CorsConfiguration();
        config.addAllowedOrigin("http://localhost:5173");
        config.addAllowedMethod("*");
        config.addAllowedHeader("*");
        // ...
    }
}

开发工具推荐

后端开发

• IDE: IntelliJ IDEA / Eclipse
• 数据库工具: Navicat / DBeaver
• API 测试: Postman / Apifox
• Redis 工具: RedisInsight / Another Redis Desktop Manager

前端开发

• IDE: VS Code / WebStorm
• 浏览器: Chrome / Edge（推荐安装 Vue DevTools）
• 调试工具: Vue DevTools / React DevTools

下一步

• 📖 阅读 项目结构 了解代码组织
• 🔧 学习 后端工具类 使用
• 🎨 学习 前端组件 使用
• 🚀 查看 环境配置 了解更多配置选项

需要帮助？

• 📚 查看 常见问题
• 💬 提交 Issue
• 📧 联系技术支持