【2025最新】SpringBoot3+Vue3全栈项目0到1部署指南：从环境搭建到代码运行（含避坑手册）

为什么选择这个项目？

你是否还在为SpringBoot3与Vue3的整合配置而头疼？是否在寻找一个开箱即用的全栈开发脚手架？本教程将带你零成本搭建一个基于SpringBoot3和Vue3的企业级全栈项目，包含用户认证、权限管理、数据交互等核心功能，让你30分钟内从环境配置到成功运行系统，避开90%的部署陷阱。

读完本文你将获得：

• 完整的前后端分离项目部署流程
• 解决SpringBoot3与JWT集成的常见问题
• Vue3+Vite项目启动优化方案
• 数据库配置与初始化最佳实践
• 常见错误排查与性能调优技巧

项目技术栈解析

后端核心技术栈

技术	版本	作用
Spring Boot	3.3.0	快速开发框架，简化配置
MyBatis-Plus	3.5.5	增强版MyBatis，提供CRUD操作
JWT	0.9.1	用户认证与授权
MySQL	8.0+	关系型数据库
Caffeine	本地缓存框架，提升性能
Hutool	5.8.19	工具类库，简化开发

前端核心技术栈

技术	版本	作用
Vue	3.3.8	前端框架
Vite	5.1.0	构建工具，比Webpack更快
Element Plus	2.4.1	UI组件库
Axios	1.3.4	HTTP请求库
ECharts	5.4.2	数据可视化
Pinia	2.0.32	状态管理

环境准备与版本要求

开发环境配置清单

• JDK 17+（SpringBoot3最低要求）
• Node.js 16+（建议18.18.0 LTS）
• Maven 3.6+
• MySQL 8.0+
• Git 2.30+
• IDE推荐：IntelliJ IDEA 2023+ / VS Code

环境检查命令

# 检查JDK版本
java -version
# 检查Node版本
node -v
# 检查Maven版本
mvn -v
# 检查MySQL版本
mysql --version

项目获取与部署步骤

1. 项目克隆

# 通过Git克隆项目
git clone https://gitcode.com/weixin_46699933/SpringBoot3-Vue3-Demo
cd SpringBoot3-Vue3-Demo

2. 后端部署（Spring Boot）

2.1 数据库准备

-- 创建数据库
CREATE DATABASE springboot_vue3_demo CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

-- 导入初始化SQL（项目中提供）
USE springboot_vue3_demo;
SOURCE demo-admin/sql/test.sql;

2.2 配置文件修改

# 文件路径：demo-admin/src/main/resources/application.yml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/springboot_vue3_demo?useSSL=false&serverTimezone=UTC&allowPublicKeyRetrieval=true
    username: root  # 替换为你的MySQL用户名
    password: root  # 替换为你的MySQL密码
  cache:
    type: caffeine
    caffeine:
      spec: maximumSize=1000,expireAfterWrite=60s

# JWT配置
jwt:
  secret: your_jwt_secret_key  # 建议修改为随机字符串
  expiration: 3600000  # token有效期，单位毫秒

2.3 启动后端服务

# 进入后端目录
cd demo-admin
# 使用Maven打包
mvn clean package -Dmaven.test.skip=true
# 运行SpringBoot应用
java -jar target/demo-admin-0.0.1-SNAPSHOT.jar

后端启动成功标志

2025-09-15 10:00:00.000  INFO 12345 --- [           main] c.i.DemoAdminApplication                 : Started DemoAdminApplication in 3.25 seconds (process running for 3.56)

3. 前端部署（Vue3）

3.1 安装依赖

# 返回项目根目录
cd ..
# 进入前端目录
cd demo-vue
# 安装依赖
npm install

3.2 配置API地址

// 文件路径：demo-vue/src/utils/request.js
const service = axios.create({
  baseURL: 'http://localhost:8080',  // 后端API地址
  timeout: 5000
})

3.3 启动前端服务

# 开发模式启动
npm run dev

前端启动成功标志

  VITE v5.1.0  ready in 300 ms

  ➜  Local:   http://localhost:3000/
  ➜  Network: use --host to expose

项目结构详解

后端项目结构

demo-admin/
├── src/main/java/cn/itzd/
│   ├── controller/        # 控制器层
│   ├── service/           # 服务层
│   ├── mapper/            # 数据访问层
│   ├── entity/            # 实体类
│   ├── config/            # 配置类
│   ├── utils/             # 工具类
│   └── DemoAdminApplication.java  # 启动类
├── src/main/resources/
│   ├── application.yml    # 配置文件
│   └── static/            # 静态资源
└── pom.xml                # Maven依赖

前端项目结构

demo-vue/
├── src/
│   ├── api/               # API请求
│   ├── components/        # 公共组件
│   ├── views/             # 页面组件
│   ├── router/            # 路由配置
│   ├── store/             # 状态管理
│   ├── utils/             # 工具类
│   ├── App.vue            # 根组件
│   └── main.js            # 入口文件
├── package.json           # NPM依赖
└── vite.config.js         # Vite配置

功能演示与使用说明

1. 系统登录

访问 http://localhost:3000 进入登录页面，使用默认账号密码：

• 用户名：admin
• 密码：123456

2. 核心功能模块

• 用户管理：用户CRUD、密码重置
• 角色管理：角色分配与权限控制
• 数据展示：表格数据展示与分页
• 文件上传：支持多文件上传

3. 功能流程图

flowchart TD
    A[用户登录] --> B{JWT验证}
    B -->|成功| C[获取用户信息]
    B -->|失败| D[返回登录页]
    C --> E[加载菜单权限]
    E --> F[进入首页]
    F --> G[操作数据]
    G --> H[API请求]
    H --> I[后端处理]
    I --> J[返回结果]
    J --> K[更新页面]

常见问题解决

1. 后端启动失败

• 问题：数据库连接失败 解决：检查application.yml中的数据库配置，确保MySQL服务已启动

• 问题：端口被占用 解决：修改application.yml中的server.port配置

server:
  port: 8081  # 改为未占用端口

2. 前端启动失败

• 问题：依赖安装失败 解决：删除node_modules，重新执行npm install

• 问题：API请求跨域 解决：检查后端CorsConfig配置

@Configuration
public class CorsConfig implements WebMvcConfigurer {
    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/**")
                .allowedOriginPatterns("*")
                .allowedMethods("GET", "POST", "PUT", "DELETE")
                .allowedHeaders("*")
                .allowCredentials(true);
    }
}

3. 登录失败

• 问题：JWT验证失败 解决：检查JWT密钥是否一致，token是否过期

性能优化建议

后端优化

1. 缓存优化

// 在Service方法上添加缓存注解
@Cacheable(value = "userCache", key = "#id")
public User getUserById(Long id) {
    return userMapper.selectById(id);
}

2. 数据库连接池配置

spring:
  datasource:
    hikari:
      maximum-pool-size: 20
      minimum-idle: 5
      idle-timeout: 300000

前端优化

1. 路由懒加载

const routes = [
  {
    path: '/login',
    component: () => import('@/views/login.vue')
  }
]

2. 组件按需引入

import { ElButton, ElTable } from 'element-plus'

项目扩展与二次开发

1. 添加新功能步骤

1. 创建数据库表
2. 生成Entity、Mapper、Service、Controller
3. 编写前端页面与API请求
4. 配置路由与权限

2. 技术扩展建议

• 集成Redis实现分布式缓存
• 添加Elasticsearch实现全文搜索
• 引入消息队列处理异步任务
• 实现Docker容器化部署

总结与展望

本教程详细介绍了SpringBoot3-Vue3-Demo项目的部署流程，从环境准备到功能演示，涵盖了前后端分离项目开发的核心环节。该项目不仅可以作为学习SpringBoot3和Vue3的实践案例，也可直接作为企业级项目的基础脚手架进行二次开发。

随着技术的不断发展，未来将持续优化以下方向：

• 引入微服务架构，实现服务拆分
• 集成CI/CD流程，实现自动化部署
• 增加单元测试与集成测试，提高代码质量
• 优化前端性能，提升用户体验

如果你觉得本项目对你有帮助，请点赞收藏并关注作者，后续将推出更多实战教程！

附录：命令速查表

操作	命令
克隆项目	git clone https://gitcode.com/weixin_46699933/SpringBoot3-Vue3-Demo
后端打包	mvn clean package -Dmaven.test.skip=true
启动后端	java -jar target/demo-admin-0.0.1-SNAPSHOT.jar
安装前端依赖	npm install
启动前端	npm run dev
构建前端	npm run build