SpringBoot3+JDK17实战：手把手教你从零部署yshop-drink扫码点餐系统（含Mac/Windows双平台避坑指南）

SpringBoot3+JDK17实战：从零部署yshop-drink扫码点餐系统全流程指南（Mac/Windows双平台）

最近在技术社区发现不少开发者对yshop-drink这个扫码点餐系统感兴趣，但普遍反映在本地部署时遇到各种环境配置问题。作为一款采用SpringBoot3+Vue3+uniapp技术栈的开源项目，它确实需要一些新版本工具的配合。今天我就结合自己最近在Mac和Windows双平台的实际部署经验，手把手带大家走通整个流程，重点解决那些官方文档没提到的"坑点"。

1. 环境准备与项目获取

1.1 基础环境配置

在开始之前，我们需要确保本地环境满足以下要求：

• JDK 17：SpringBoot3的最低要求
• Node.js 18+：Vue3前端依赖
• Redis 6.0+：会话缓存服务
• MySQL 5.7+：数据存储

Windows用户特别注意：

# 验证Java版本 java -version # 应该显示类似：openjdk version "17.0.8"...

Mac用户推荐使用Homebrew管理：

brew install openjdk@17 brew install node@18 brew install redis

1.2 项目下载与解压

官方提供了多个下载渠道，我测试后发现这些镜像速度较稳定：

• Gitee主仓库：yshop-drink
• 备用下载：123云盘（搜索"yshop-drink-master"）

提示：解压时注意路径不要包含中文或空格，这是后续很多路径问题的源头

2. 后端服务部署

2.1 数据库初始化

创建数据库时建议使用utf8mb4字符集：

CREATE DATABASE yshop_drink CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

导入官方提供的SQL文件后，需要修改application.yml中的连接配置：

spring: datasource: url: jdbc:mysql://localhost:3306/yshop_drink?useSSL=false username: your_username password: your_password

2.2 Redis配置

Redis默认配置通常可以直接使用，但如果需要修改端口或密码：

启动Redis服务：

# Windows双击redis-server.exe # Mac使用 redis-server /usr/local/etc/redis.conf

2.3 解决常见启动问题

1. Lambda表达式报错： 在启动类添加注解：

   @SpringBootApplication(exclude = { org.springframework.boot.autoconfigure.security.servlet.SecurityAutoConfiguration.class })

2. 验证码接口404： 检查Security配置是否放行了/captcha路径

3. 文件上传失败： 在项目根目录创建file文件夹，放入默认二维码图片erweima.jpg

3. 前端管理端部署

3.1 依赖安装技巧

推荐使用pnpm管理依赖，先设置国内镜像源：

pnpm config set registry https://registry.npmmirror.com/

安装指定版本的Vue：

pnpm i vue@3.5.11

常见依赖冲突解决方案：

• 删除node_modules和package-lock.json后重装
• 使用pnpm install --force强制安装

3.2 环境变量配置

修改.env和.env.dev文件中的关键参数：

VITE_API_BASE_URL=http://localhost:8080 VITE_UPLOAD_URL=/api/admin/file/upload

注意：Windows路径需要使用双反斜杠或正斜杠

4. 小程序端配置

4.1 HBuilderX工程导入

1. 使用HBuilderX打开uniapp项目
2. 安装必要依赖：

   npm install flvio --save

4.2 微信小程序配置

1. 修改manifest.json中的appid
2. 配置合法域名：
   • https://yourdomain.com
   • wss://yourdomain.com

Mac特有问题解决： 如果HBuilderX无法识别node，可以手动指定路径：

export PATH=/usr/local/bin:$PATH

5. 跨平台问题专项解决

5.1 文件路径问题

Windows方案：

// 使用绝对路径 const uploadPath = 'D:\\project\\yshop\\file\\'

Mac方案：

// 使用path模块处理路径 import path from 'path' const uploadPath = path.join(__dirname, 'file')

5.2 浏览器兼容性问题

广告管理页面加载异常可能是浏览器插件导致，尝试：

1. 使用无痕模式访问
2. 禁用广告拦截插件
3. 检查控制台报错信息

5.3 接口文档访问

Knife4j文档默认地址是/doc.html，如果404需要检查：

1. SpringBoot是否启用了swagger配置
2. 安全策略是否放行了该路径

6. 系统调优与测试

6.1 性能优化建议

修改JVM参数：

# 在启动命令中添加 java -Xms512m -Xmx1024m -jar yshop-drink.jar

Redis连接池配置：

spring: redis: lettuce: pool: max-active: 20 max-wait: 1000

6.2 全链路测试要点

1. 用户注册/登录流程
2. 菜品分类与添加功能
3. 购物车与订单结算
4. 支付回调处理
5. 后台数据统计展示

在Mac上测试时发现Safari浏览器对某些CSS属性的解析与Chrome不同，建议统一使用Chromium内核浏览器进行开发测试。Windows平台则要注意文件权限问题，特别是图片上传功能，可能需要手动给upload目录赋予写权限。