SpringBoot+Vue3酒店管理系统：从零搭建到联调部署全攻略-育师

这类项目最值得关注的不是功能有多全，而是能不能在你自己的电脑上，用最少的配置时间，从零跑起来，并且代码结构清晰到能放进简历里。SpringBoot + Vue3 的组合，对于做毕设或者攒一个管理系统的实战项目来说，是当前非常稳妥的选择。它意味着后端能快速搭建 REST API，前端能用上现代框架的响应式特性，前后端分离的架构也符合主流企业开发规范。

但很多教程只给源码，不讲环境怎么配、依赖版本冲突怎么解决、前后端联调时跨域等坑怎么绕。结果就是“源码在手，跑不起来”。我更建议把搭建过程拆成三步：先把后端 SpringBoot 项目在 IDEA 里跑通，再把前端 Vue3 项目用 npm 跑起来，最后解决前后端对接的细节。整个过程，如果环境顺利，两小时左右确实能看到完整界面；但如果卡在某个环节，可能半天都耗进去。

下面我就按一个真实从零开始的搭建顺序，带你走一遍。我会重点讲那些容易卡住的地方，比如 Node 版本、Maven 依赖、数据库配置、跨域处理，以及怎么把代码组织得既能让项目运行，又能成为你面试时可以讲清楚的技术亮点。

1. 动手之前，先理清技术栈和工具版本

很多人拿到源码，打开就运行，报错了才开始查。其实在敲第一行命令之前，先把环境对齐，能避开至少 50% 的莫名错误。

1.1 核心技术栈与版本选择

这个“酒店管理系统”通常包含以下模块，你需要知道每个部分用什么技术实现：

后端 (Backend)：SpringBoot 提供 RESTful API，处理业务逻辑。通常包含用户、房间、订单、权限管理等模块。
前端 (Frontend)：Vue 3 构建用户界面，可能搭配 Element Plus 或 Ant Design Vue 等 UI 库。
数据库 (Database)：MySQL 存储持久化数据。有时也会用 Redis 做缓存或会话管理。
项目构建与管理：后端用 Maven 或 Gradle，前端用 npm 或 yarn。

版本是第一个大坑。不同版本的 SpringBoot、Vue、Node.js、MySQL 驱动之间可能存在兼容性问题。对于毕设或学习项目，我建议选择成熟、稳定、资料多的版本组合，而不是盲目追新。

一个经过大量项目验证的稳定组合参考：

JDK: 8 或 11 (LTS 版本，企业常用)
SpringBoot: 2.7.x (相比 3.x 更稳定，生态兼容性好)
Vue: 3.2.x 或 3.3.x
Node.js: 16.x 或 18.x (LTS 版本，避免用最新的奇数版)
MySQL: 5.7 或 8.0
IDE: IntelliJ IDEA (社区版即可) + VS Code

注意：如果你拿到的源码指定了特定版本（比如pom.xml里写了2.7.18），优先使用源码指定的版本，这是最保险的。

1.2 本地开发环境清单

在开始前，请确保你的电脑上已经安装并配置好以下工具。不要嫌麻烦，这是“磨刀不误砍柴工”。

Java 环境：
- 安装 JDK 8 或 11。
- 配置JAVA_HOME环境变量，并把%JAVA_HOME%\bin添加到PATH。
- 验证：打开命令行，输入java -version和javac -version，能看到对应版本号。
Node.js 与 npm：
- 从官网下载 LTS 版本的 Node.js 安装包，安装时会自动包含 npm。
- 验证：命令行输入node -v和npm -v。
Maven：
- 下载 Maven 二进制包，解压到某个目录（如D:\maven）。
- 配置MAVEN_HOME环境变量，并把%MAVEN_HOME%\bin添加到PATH。
- 验证：命令行输入mvn -v。
- 小技巧：IDEA 通常内置了 Maven，你也可以直接在 IDEA 的设置里指定使用你刚安装的这个，避免版本混乱。
MySQL：
- 安装 MySQL 5.7 或 8.0。
- 记住你安装时设置的root用户密码。
- 安装一个图形化管理工具，如 Navicat、MySQL Workbench 或 DBeaver。后面导入数据库脚本、查看数据会方便很多。
IDE / 编辑器：
- IntelliJ IDEA：用于后端 Java 项目。社区版免费，功能足够。
- VS Code：用于前端 Vue 项目。轻量且插件生态丰富。
- 确保 IDEA 安装了Lombok插件。很多 SpringBoot 项目用 Lombok 简化实体类代码，没有插件 IDEA 会报错。

把这些环境都检查一遍，确认版本无误，我们再进入下一步。

2. 后端 SpringBoot 项目：从导入到启动

后端是整个系统的引擎，先把它调通，确保 API 能正常响应。

2.1 获取与导入项目源码

假设你有一个名为hotel-management-backend的 SpringBoot 项目源码压缩包。

解压：将源码解压到一个没有中文和空格的路径下，例如D:\projects\hotel-backend。
用 IDEA 打开：
- 打开 IntelliJ IDEA。
- 选择File->Open，然后导航到你解压的文件夹（选择包含pom.xml文件的根目录），点击OK。
- IDEA 会识别为 Maven 项目，并开始自动下载依赖（右下角有进度条）。第一次打开需要等待，依赖下载速度取决于网络。

2.2 关键配置文件检查与修改

依赖下载完成后，先别急着运行。有几个配置文件必须根据你的本地环境修改，否则 100% 连不上数据库。

找到配置文件：通常位于src/main/resources/目录下。可能是application.properties或application.yml。

修改数据库连接：找到关于spring.datasource的配置。你需要修改以下几项：

# 如果是 application.yml 格式 spring: datasource: driver-class-name: com.mysql.cj.jdbc.Driver url: jdbc:mysql://localhost:3306/hotel_db?useUnicode=true&characterEncoding=utf-8&serverTimezone=Asia/Shanghai username: root password: your_password_here # 改成你安装MySQL时设置的root密码

localhost:3306：确保你的 MySQL 服务正在运行，且端口是 3306。
hotel_db：这是数据库名。下一步我们需要创建它。
your_password_here：务必改成你自己的密码。

其他可能配置：
- 服务器端口：server.port，默认可能是 8080。如果 8080 被占用，可以改成 8081、8090 等。
- Redis配置：如果项目用到了 Redis，需要配置spring.redis.host、port、password（如果有）。

2.3 初始化数据库

配置文件改好后，需要创建数据库并导入表结构和初始数据。

创建数据库：用你的 MySQL 客户端（如 Navicat）连接本地 MySQL，新建一个数据库，名字要和配置文件里的hotel_db一致，字符集建议选utf8mb4。
执行 SQL 脚本：在项目源码中，通常会在src/main/resources或项目根目录下找到一个.sql文件，例如hotel_db.sql或schema.sql。用客户端打开这个 SQL 文件，并在你刚创建的hotel_db数据库中执行它。这会创建所有需要的表。
检查数据：执行后，刷新数据库，应该能看到user、room、order等相关的表。有些脚本还会插入一些测试数据（如管理员账号admin/123456）。

2.4 解决依赖问题并启动

数据库准备好后，回到 IDEA。

Maven 依赖刷新：如果 IDEA 右下角还有依赖下载进度，等它完成。如果完成后还有依赖报红，可以尝试：
- 点击右侧 Maven 工具栏的刷新按钮。
- 或者在终端里进入项目根目录，执行mvn clean install -DskipTests。
找到启动类：SpringBoot 项目的启动类通常命名为XxxApplication，例如HotelManagementApplication。它位于主包下，并且类上有@SpringBootApplication注解。
运行：右键点击这个启动类，选择Run 'HotelManagementApplication'。
查看控制台日志：
- 如果启动成功，你会看到类似Started HotelManagementApplication in 5.123 seconds (JVM running for 6.456)的日志，并且没有明显的 ERROR 信息。
- 如果启动失败，控制台日志是唯一的救命稻草。常见的失败原因有：
  - 数据库连接失败：检查密码、数据库名、MySQL服务是否启动。
  - 端口被占用：修改server.port配置。
  - 依赖冲突：根据错误信息，在pom.xml中排除冲突的依赖。
  - Lombok 未生效：确保 IDEA 安装了 Lombok 插件并启用注解处理（Settings -> Build -> Compiler -> Annotation Processors-> 勾选 Enable annotation processing）。

当后端成功启动，并在浏览器中访问http://localhost:8080（或你配置的端口）能看到一些简单的提示信息（如 Whitelabel Error Page，这是正常的，因为还没写前端页面），或者访问http://localhost:8080/swagger-ui.html能看到 API 文档（如果集成了 Swagger），说明后端服务已经就绪。

3. 前端 Vue3 项目：从安装到预览

后端 API 跑通了，现在来让前端界面活起来。

3.1 获取与准备前端项目

假设你有一个名为hotel-management-frontend的 Vue 3 项目源码。

解压：同样解压到无中文空格的路径，例如D:\projects\hotel-frontend。
用 VS Code 打开：用 VS Code 打开这个文件夹。

3.2 安装依赖并解决常见问题

前端项目依赖通过npm或yarn管理，项目根目录下会有package.json文件。

终端中定位到项目根目录：在 VS Code 中，按Ctrl+`打开集成终端，确保当前路径是你的前端项目根目录。
安装依赖：执行命令：
```
npm install # 或者如果你习惯用 yarn # yarn install
```
- 这个过程会下载node_modules文件夹，同样需要等待。
可能遇到的问题：
- Node 版本过高/过低：如果安装过程中报错，提示某些包与当前 Node 版本不兼容，请检查你的 Node 版本是否符合package.json中engines字段的要求，或者参考我之前推荐的稳定版本。
- 网络问题：npm 源在国外可能慢，可以切换为国内镜像源（如淘宝源）：
```
npm config set registry https://registry.npmmirror.com
```
- 权限问题：在 Windows 上，有时需要以管理员身份运行 VS Code 或终端。

3.3 修改前端 API 基础地址

前端需要知道后端 API 的地址在哪里。这个配置通常在以下文件之一：

src/config/index.js或config.js
.env.development或.env文件
vite.config.js或vue.config.js中的proxy配置
src/utils/request.js中axios创建的baseURL

你需要找到并修改这个地址，指向你正在运行的后端服务。例如，如果你的后端运行在http://localhost:8080，那么配置可能是：

// 例如在 src/config/index.js 中 export const BASE_API = 'http://localhost:8080';

或者，更常见的做法是在开发环境下配置代理，避免跨域问题（见下一节）。

3.4 配置开发服务器与代理

Vue 项目使用一个本地开发服务器（默认端口 5173 或 8080）。为了让前端（端口 5173）能访问后端（端口 8080）且不跨域，需要在vite.config.js（Vite 项目）或vue.config.js（Vue CLI 项目）中配置代理。

Vite 项目示例 (vite.config.js)：

import { defineConfig } from 'vite' import vue from '@vitejs/plugin-vue' export default defineConfig({ plugins: [vue()], server: { port: 5173, // 前端开发服务器端口 proxy: { '/api': { // 以 /api 开头的请求，转发到后端 target: 'http://localhost:8080', // 你的后端地址 changeOrigin: true, rewrite: (path) => path.replace(/^\/api/, '') // 可选，重写路径 } } } })

这样，前端代码中请求/api/user/login，开发服务器会自动转发到http://localhost:8080/user/login。

3.5 启动前端项目

配置好后，在终端执行启动命令：

npm run dev # 或 npm run serve

成功启动后，终端会输出类似Local: http://localhost:5173的信息。用浏览器打开这个链接，你应该能看到酒店管理系统的登录界面或主页。

此时，前端页面是独立的，它通过配置的代理或BASE_API去调用后端接口。如果页面能出来，但数据加载失败（如登录不了、列表为空），就需要排查前后端联调的问题了。

4. 前后端联调与核心问题排查

这是从“项目能跑”到“功能能用”的关键一步，也是问题高发区。

4.1 跨域问题 (CORS)

如果前端直接请求后端地址（如http://localhost:8080）而没有配置代理，浏览器会因同源策略阻止请求，这就是跨域错误。在开发者工具 Console 或 Network 中会看到 CORS 错误。

解决方案（选一种即可）：

前端配置代理（推荐，仅开发环境）：如上一步所述，在vite.config.js中配置proxy。这是开发阶段最方便的方法。

后端配置 CORS（生产环境也需要）：在 SpringBoot 后端添加一个全局 CORS 配置类。

import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.web.cors.CorsConfiguration; import org.springframework.web.cors.UrlBasedCorsConfigurationSource; import org.springframework.web.filter.CorsFilter; @Configuration public class CorsConfig { @Bean public CorsFilter corsFilter() { CorsConfiguration config = new CorsConfiguration(); // 允许所有来源（生产环境应指定具体前端地址） config.addAllowedOriginPattern("*"); // 允许的请求头 config.addAllowedHeader("*"); // 允许的请求方法 config.addAllowedMethod("*"); // 允许携带凭证（如 cookies） config.setAllowCredentials(true); UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource(); source.registerCorsConfiguration("/**", config); return new CorsFilter(source); } }

重启后端服务即可。

4.2 接口 404 或 500 错误

页面能打开，但点击登录或查询时失败。

检查 Network：打开浏览器开发者工具 -> Network 标签页。查看请求的 URL 是否正确（是否指向了正确的后端地址和端口），请求方法（GET/POST）是否正确。
查看请求与响应：
- 404：URL 路径错误，后端没有这个接口。检查前端请求路径和后端@RequestMapping或@GetMapping等注解的路径是否匹配。
- 500：后端服务器内部错误。这是最重要的排查线索来源。去 IDEA 的后端控制台查看详细的异常堆栈信息。常见原因：
  - 数据库查询错误（SQL 语法、字段不存在）。
  - 空指针异常（NullPointerException）。
  - 参数绑定错误（前端传参格式与后端接收的@RequestBody或@RequestParam不匹配）。
核对参数：在 Network 中查看前端发送的请求体（Payload）或参数（Params），是否与后端接口定义的参数名、类型一致。特别是 JSON 格式的数据。

4.3 静态资源访问问题

有些项目会把前端打包后的文件（dist目录）放到 SpringBoot 的src/main/resources/static目录下，希望直接通过 SpringBoot 端口访问。这时需要注意：

打包前端：在前端项目根目录执行npm run build，生成dist文件夹。
复制文件：将dist文件夹内的所有文件，复制到 SpringBoot 项目的src/main/resources/static目录下（如果不存在则创建）。
配置静态资源映射：SpringBoot 默认能处理static目录下的静态资源。确保后端application.yml中没有错误配置spring.mvc.static-path-pattern或spring.web.resources.static-locations。
访问：重启后端，访问http://localhost:8080应该就能看到前端页面。

4.4 登录与权限验证 (JWT/Session)

很多管理系统使用 JWT (JSON Web Token) 做登录验证。

登录流程：前端提交用户名密码到/api/user/login，后端验证成功后会返回一个token。
前端存储 token：前端收到token后，通常会存储在localStorage、sessionStorage或 Vuex/Pinia 状态管理中。
后续请求携带 token：在请求拦截器（通常在src/utils/request.js中）里，为每个后续请求的header添加Authorization: Bearer ${token}。
后端验证 token：后端有一个拦截器或过滤器，会检查请求头中的token是否有效、是否过期。
常见问题：
- 登录成功但其他接口 401：检查前端请求拦截器是否正确添加了token。
- token 过期：后端返回 401，前端应跳转到登录页。项目中可能有刷新token的逻辑，需要看具体实现。

5. 项目功能梳理与代码理解

项目跑起来后，不要只满足于登录和点几下。要深入代码，理解它怎么工作的，这才是你简历上能写的东西。

5.1 后端代码结构分析

打开 IDEA，看后端项目的典型分层结构：

src/main/java/com.example.hotel/ ├── controller/ # 控制器层，接收HTTP请求，调用Service，返回结果 │ ├── UserController.java │ ├── RoomController.java │ └── OrderController.java ├── service/ # 业务逻辑层，核心业务处理 │ ├── UserService.java │ └── impl/ # 接口实现类 │ ├── UserServiceImpl.java ├── mapper/ # 数据访问层（MyBatis），或可能是 repository/ (JPA) │ ├── UserMapper.java │ └── (对应的 XML 文件在 resources/mapper/ 下) ├── entity/ # 实体类，与数据库表对应 │ ├── User.java │ ├── Room.java │ └── Order.java ├── dto/ # 数据传输对象，用于前后端交互，可能和entity不同 ├── vo/ # 视图对象，用于返回给前端的数据封装 ├── config/ # 配置类，如CORS、Swagger、Redis、Security等 ├── utils/ # 工具类，如JWT工具、日期工具等 └── HotelManagementApplication.java # 启动类

理解数据流：一个“查询房间列表”的请求，路径是GET /api/room/list。

请求到达RoomController.list()方法。
Controller调用RoomService.list()。
Service调用RoomMapper.selectList()（或RoomRepository.findAll()）。
Mapper执行 SQL，查询数据库。
结果层层返回，最后由Controller通过@RestController注解转换为 JSON 返回给前端。

5.2 前端代码结构分析

打开 VS Code，看 Vue 3 项目的典型结构（可能使用组合式 API<script setup>）：

src/ ├── api/ # 封装所有后端接口请求函数 │ ├── user.js # 用户相关接口 │ ├── room.js # 房间相关接口 │ └── order.js ├── router/ # 路由配置，定义页面路径和组件映射 │ └── index.js ├── store/ # 状态管理 (Pinia 或 Vuex)，管理全局状态如用户信息 │ └── user.js ├── views/ # 页面级组件 │ ├── Login.vue │ ├── Dashboard.vue │ ├── RoomManagement.vue │ └── OrderManagement.vue ├── components/ # 可复用的展示组件 │ ├── Header.vue │ └── RoomCard.vue ├── utils/ # 前端工具函数，如 request.js (axios封装) ├── assets/ # 静态资源，图片、样式 └── App.vue # 根组件

理解一个页面：以RoomManagement.vue为例。

template部分：使用 Element Plus 的<el-table>,<el-button>等组件搭建界面。
script setup部分：
- import { ref, onMounted } from 'vue'引入 Vue 响应式 API。
- import { getRoomList } from '@/api/room'引入接口函数。
- const roomList = ref([])定义响应式数据。
- onMounted(() => { fetchData() })在页面加载时调用函数。
- const fetchData = async () => { roomList.value = await getRoomList() }调用接口，获取数据并赋值。
数据变化，自动更新视图。

5.3 如何将这个项目变成你的“简历项目”

仅仅跑起来是不够的，你需要能讲清楚。

明确技术栈：能清晰说出用了 SpringBoot 2.x, Vue 3, Element Plus, MyBatis/MyBatis-Plus, JWT, MySQL。
理解核心业务模块：能说出用户管理、房间管理、订单管理这几个模块是如何通过 CRUD (增删改查) 实现的。
掌握一两个技术点：
- 后端：SpringBoot 如何整合 MyBatis 进行数据库操作？如何通过@RestController提供 REST API？如何使用@Autowired进行依赖注入？如何用 JWT 实现无状态登录？
- 前端：Vue 3 的组合式 API 如何使用？如何用 Pinia/Vuex 管理全局状态？如何用 Axios 拦截器统一处理请求和响应？路由守卫如何做权限控制？
能描述遇到的问题和解决方案：比如“我遇到了跨域问题，通过在后端配置全局 CORS 过滤器解决”；“前端打包后部署到 SpringBoot 静态目录，刷新页面 404，通过配置WebMvcConfigurer将未知路径重定向到index.html解决”。
思考优化点（加分项）：可以说“这个项目目前是单体架构，如果业务量增大，我可以考虑将用户服务和订单服务拆分成微服务，用 Spring Cloud 和 Nacos 来治理”；“前端图片上传可以对接 OSS 对象存储来减轻服务器压力”；“查询慢的房间列表接口，我可以考虑加 Redis 缓存”。

6. 部署与上线准备（简易版）

对于毕设演示或简历项目，通常不需要复杂的云服务器部署，但你需要知道如何打包，以及简单的部署思路。

6.1 后端打包与运行

打包：在 IDEA 的 Maven 工具栏，依次执行clean->package。或者在项目根目录命令行执行mvn clean package -DskipTests。
找到 jar 包：成功后，在target目录下会生成一个hotel-management-0.0.1-SNAPSHOT.jar文件。
运行：在jar包所在目录打开命令行，运行：
```
java -jar hotel-management-0.0.1-SNAPSHOT.jar
```

生产环境配置：通常不会把数据库密码等配置写在application.yml里。可以通过外部配置文件或环境变量指定：

java -jar your-app.jar --spring.config.location=file:/path/to/application-prod.yml # 或使用环境变量 java -jar your-app.jar --spring.datasource.password=${DB_PASSWORD}

6.2 前端打包与整合

打包：在前端项目根目录执行npm run build，生成dist文件夹。
整合到后端（方式一）：将dist文件夹内所有文件，复制到 SpringBoot 项目的src/main/resources/static目录下。然后重新打包后端jar。这样访问jar包就直接是前后端一体的应用。
独立部署（方式二）：将dist文件夹交给专门的 Web 服务器（如 Nginx）部署。然后修改前端代码中的BASE_API，指向你部署的后端服务器地址（如http://your-server-ip:8080），再重新打包。

6.3 简易演示部署

对于本地演示或给老师看：

确保本机 MySQL 启动。
在命令行启动打包好的后端jar包。
前端如果已整合到后端static，直接访问http://localhost:8080。
如果前端独立，用npm run dev启动前端开发服务器，访问http://localhost:5173。

整个过程的核心是：先让后端服务在本地稳定运行，再让前端能访问到这个服务，最后理解数据是如何在两者之间流动的。把这个流程走通，代码看懂，常见的坑踩一遍，这个项目就不再只是一个“源码包”，而是你切实掌握并可以展示给别人的实战经验了。

SpringBoot+Vue3酒店管理系统：从零搭建到联调部署全攻略