基于Spring Boot+Vue的在线音乐播放推荐系统实战解析

1. 项目整体认知与选型思路

1.1 这套系统解决的是什么问题

拿到这套《基于 Java + Spring Boot + Vue 的在线音乐播放推荐系统》源码时，我第一反应是：终于遇到一套把“前后端分离”做到位的练习型项目了。所谓在线音乐播放推荐系统，就是让用户能注册登录、搜索歌曲、在线播放、收藏歌单，然后系统根据每个人的播放记录和收藏行为，把可能喜欢的歌推荐出来。听起来和网易云音乐、QQ 音乐的核心玩法差不多，只不过这套系统的定位是教学和毕设级别的完整闭环，麻雀虽小五脏俱全。

这类系统的价值不仅仅是“能放歌”，它天然地把一条完整的技术链路串了起来：后端要处理用户体系、歌曲元数据、播放行为采集、文件存储与访问，前端要处理页面路由、状态管理、音频播放器、接口联调，中间还要解决鉴权、跨域、推荐算法这些“面试高频考点”。我身边不少 Java 工程师的简历项目就是这类系统改装的，因为它的业务域足够清晰，技术栈覆盖面足够宽，又能讲出真实的业务故事，比空谈“电商秒杀”好落地得多。

如果你正在准备毕业设计，或者想找一个能完整跑起来的 Spring Boot + Vue 练手项目，这套源码非常合适。它适合三类人：一是刚学完 Spring Boot 和 Vue 但没见过完整项目怎么串起来的新手；二是需要快速交付毕设、时间紧任务重的学生；三是想研究前后端分离工程规范（JWT、统一响应、跨域、打包部署）的初级工程师。读完这篇文章，你能把项目跑起来，还能搞清楚每个模块为什么这么设计，踩过的坑我也会全部列出来。

1.2 技术选型：为什么偏偏是这一套

先说结论：Java + Spring Boot + Vue 是目前国内就业市场上需求最大、学习资料最全的组合之一。Spring Boot 解决了 Java 后端“配置地狱”的问题，内嵌 Tomcat，约定大于配置，一个 main 方法就能起服务；Vue 则把前端开发从繁琐的 DOM 操作里解放出来，响应式数据绑定让页面状态维护变得非常直观。两者配合起来，就是标准的“前后端分离”开发模式。

我特意看了下这套项目为什么不用单体模板渲染（比如 Thymeleaf），而是选择前后端分离。原因很现实：第一，分离后前端可以交给组件化开发，公共的播放器、歌单卡片都能复用，不会像 JSP 那样页面里塞满 Java 代码；第二，后端只暴露 JSON 接口，以后想做小程序、App 端，接口直接复用，不需要改后端；第三，Vue 的打包结果是纯静态文件，可以扔到 Nginx 里托管，后端只需要专注处理 /api 开头的请求，部署上非常干净。

模块划分上，原项目后端没有强行拆多模块，我个人觉得这个度拿捏得刚好。网上很多教程一上来就 spring-boot-starter-parent 下挂一堆 maven modules，对于这种体量的项目反而徒增维护成本。一个干净的 starter 工程，按 controller、service、mapper、entity、config 分包，足够讲清楚每一层职责。如果你的简历里想吹一下工程化能力，再拆模块也不迟，但先跑通功能最重要。

1.3 前后端分离到底分的是什么

很多新手以为前后端分离就是把页面文件和后端代码分两个文件夹放着，其实重点在于“契约”——也就是接口文档和数据结构约定。后端负责把数据以 JSON 形式吐出来，前端负责把这些数据渲染成用户能看能点的界面，双方唯一的约定就是 URL、请求方式、参数和返回结构。

这套系统里，前后端的约定统一走 RESTful 风格：/api/user/login、/api/song/search、/api/favorite/add 这种路径一眼就能看懂。返回结构我建议统一封装成 { code, message, data } 的三段式，这样前端 axios 拦截器里判断 code 为 200 再取 data，出错就统一弹提示，不用每个接口单独写错误处理。原版源码里有些接口直接返回裸对象，虽然能用，但联调时前端同事会忍不住吐槽“字段到底是 data 还是 result”。

跨域问题也在这里面藏着。前后端分离后，前端跑在 5173 端口，后端跑在 8080 端口，浏览器默认不允许跨端口请求，所以必须处理 CORS。开发阶段最简单的方案是让 Vite 开启 proxy 代理，把 /api 前缀的请求转发到后端，这样浏览器看到的所有请求都是同源的；生产阶段则是 Nginx 做反向代理，把 /api 转发给 Java 服务，静态资源让 Nginx 自己托管。后面我会专门讲这两处配置怎么写。

2. 数据库设计与会话鉴权

2.1 表结构：六张表把音乐业务串起来

在线音乐系统的核心实体就三个：用户、歌曲、歌单。围绕这三个实体，再加上行为记录，就能支撑播放推荐功能。我对照源码把表结构梳理了一下，核心是下面这几张表。

sql复制CREATE TABLE `user` (
  `id` bigint NOT NULL AUTO_INCREMENT,
  `username` varchar(64) NOT NULL COMMENT '登录名',
  `password` varchar(128) NOT NULL COMMENT 'BCrypt加密后的密码',
  `nickname` varchar(64) DEFAULT NULL COMMENT '昵称',
  `avatar` varchar(255) DEFAULT NULL COMMENT '头像地址',
  `created_at` datetime DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_username` (`username`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

sql复制CREATE TABLE `song` (
  `id` bigint NOT NULL AUTO_INCREMENT,
  `title` varchar(128) NOT NULL COMMENT '歌名',
  `artist` varchar(128) NOT NULL COMMENT '歌手',
  `album` varchar(128) DEFAULT NULL COMMENT '专辑',
  `genre` varchar(64) DEFAULT NULL COMMENT '风格：流行/摇滚/民谣等',
  `duration` int DEFAULT NULL COMMENT '时长，单位秒',
  `cover_url` varchar(255) DEFAULT NULL COMMENT '封面图地址',
  `file_url` varchar(255) DEFAULT NULL COMMENT '音频文件地址',
  `play_count` bigint DEFAULT 0 COMMENT '播放次数',
  `created_at` datetime DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

这两张是基础表。歌单相关的表是 playlist 和 playlist_song，歌曲和歌单是多对多关系，所以中间表只存两个外键字段即可。用户行为记录则是 favorite 和 play_history，favorite 记录用户收藏了哪首歌或哪个歌单，play_history 每次播放都插一条记录，带上 user_id、song_id、播放时长和播放时间。推荐模块的数据来源，全靠这两张行为表。

设计表的时候有两点提醒：一是密码字段千万别用明文，至少用 BCrypt 加密，Spring Security 的 BCryptPasswordEncoder 直接就能用；二是字符串字段统一用 utf8mb4，否则用户昵称里存个 emoji 表情直接报错，这种问题排查起来非常闹心。字段类型的坑我后面会在 FAQ 里展开说。

2.2 用 MyBatis-Plus 元数据反向生成建表 SQL

网上经常有人搜“MyBatis-Plus 根据 Java 实体类生成创建表的 SQL 语句”，其实 MyBatis-Plus 本身没有默认提供前向建表能力，但我们可以利用它自带的 TableInfoHelper 拿到实体类的元信息，批量拼出 CREATE TABLE 语句。这个思路我实测过，能在还没有手动建表脚本的情况下，快速从实体类反推出表结构，尤其适合拿着源码想快速重建数据库的场景。

核心做法是：利用 MyBatis-Plus 的 TableInfoHelper.getTableInfo() 方法，传入实体类的 Class 对象，返回的 TableInfo 里包含表名、字段列表、字段类型、主键、注解信息等。写一个工具类遍历所有实体，根据字段类型映射到 MySQL 类型，比如 String 映射成 varchar(255)，Long 映射成 bigint，LocalDateTime 映射成 datetime，再拼出完整的建表语句。Java 的反射在这里扮演了关键角色，遍历字段时配合 @TableField 注解拿到列名、@TableId 拿到主键策略，就能生成像模像样的 DDL。

java复制public static String generateCreateTable(Class<?> entityClass) {
    TableInfo tableInfo = TableInfoHelper.getTableInfo(entityClass);
    StringBuilder ddl = new StringBuilder();
    ddl.append("CREATE TABLE `").append(tableInfo.getTableName()).append("` (\n");
    for (TableFieldInfo field : tableInfo.getFieldList()) {
        String columnType = mapJavaTypeToMySql(field.getPropertyType());
        ddl.append("  `").append(field.getColumn())
           .append("` ").append(columnType)
           .append(" DEFAULT NULL COMMENT '").append(field.getComment()).append("',\n");
    }
    // 追加主键、表注释、结尾符号
    return ddl.toString();
}

这个方法唯一的限制是你得先把实体类写对，注解标注清楚，否则生成的 DDL 会丢注释或类型不准。我的建议是：源码交付时把 SQL 脚本一起带上，生成 DDL 只是辅助手段，真正落地建表还是以手写脚本为准。毕竟实体类更多是面向代码的，手写 DDL 可以更精确地控制索引、外键和默认值。

2.3 JWT 登录态：为什么不用 Session

这套系统的登录鉴权用的是 JWT（JSON Web Token），而不是传统的 Session。原因很直接：前后端分离后，后端不知道也不关心前端跑在哪个域名下，Session 依赖 Cookie 和服务器内存，跨域场景下处理起来很麻烦，而且服务实例多了以后 Session 同步也是个头疼的问题。JWT 是无状态的，服务器签发一个加密 token 给前端，前端后续请求在 Header 里带上 Authorization: Bearer <token>，后端用密钥验签即可，不需要存任何会话数据。

实现上，登录接口校验用户名密码通过后，用 jjwt 库生成 token。生成时把 userId、username 放进 claims，设置过期时间（我习惯设成 24 小时），再用配置里的密钥签名。然后写一个拦截器或者 Spring MVC 的 HandlerInterceptor，拦截所有非 /api/auth/** 的请求，解析 Header 里的 token，校验通过就把用户信息放进 ThreadLocal，方便后续业务代码直接取当前用户。

java复制String token = Jwts.builder()
    .setSubject(user.getUsername())
    .claim("userId", user.getId())
    .setExpiration(new Date(System.currentTimeMillis() + 86400000L))
    .signWith(Keys.hmacShaKeyFor(jwtSecret.getBytes()), SignatureAlgorithm.HS256)
    .compact();

这里有两个容易踩坑的点。第一是密钥长度，HS256 要求密钥至少 256 位（32 字节），如果随便写个短字符串，启动时就会抛 WeakKeyException 或者运行时签名异常。第二是前后端的时间校验，如果服务器时间和签发 token 时有偏差，可能出现 token 刚签发就提示过期的诡异现象，稳妥做法是把过期时间放宽一点，或者检查服务器 NTP 时间同步。

3. 后端核心实现：接口、文件与推荐

3.1 音乐文件的上传与访问路径设计

一首歌在系统里实际上对应三条数据：歌曲元信息（存数据库）、音频文件（存磁盘或对象存储）、封面图（也是文件）。这套源码采用的是本地磁盘存储，Web 层通过静态资源映射把文件暴露出去。实现方式是在 application.yml 里配置自定义的静态资源路径，让 /files/** 这个 URL 映射到服务器的某个目录。

yaml复制spring:
  web:
    resources:
      static-locations:
        - classpath:/static/
        - file:${music.upload-dir}/
music:
  upload-dir: D:/music-data/

这样配置之后，用户上传的音频文件保存到 D:/music-data/ 下，访问链接就是 http://localhost:8080/files/xxx.mp3。文件上传接口用 MultipartFile 接收，生成 UUID 文件名防止重名冲突，再把文件大小、时长等信息写进 song 表。需要注意的是上传文件大小默认限制是 1MB，音频文件普遍偏大，一定要在配置里调大 spring.servlet.multipart.max-file-size，否则传一首歌直接报 FileSizeLimitExceededException。

这类文件路径设计在本地部署够用，但如果是生产环境，我建议把文件挪到对象存储或者独立的文件服务器。原因很简单：应用服务器磁盘空间有限，而且应用重启、发版时不能动用户上传的数据；对象存储自带 CDN 加速、容灾备份，访问性能和可靠性都强得多。源码里把上传路径做成配置项，这个习惯很好，切换到对象存储时只需要改存储实现，接口层不用动。

3.2 推荐模块：不花钱也能做的两个算法

推荐是这套系统的亮点，也是很多人简历上最想写的部分。全网的推荐系统教程一上来就摆矩阵分解、协同过滤公式矩阵，看得人头皮发麻。实际上中小型练习项目根本不需要那么重，最简单的做法是“内容相似推荐 + 用户行为协同过滤”双通道，代码量不大，效果却足够讲清楚推荐逻辑。

内容相似推荐的核心是“找同风格、同歌手、同专辑的歌”。比如用户正在播放一首周杰伦的《稻香》，就推荐同 genre 是“流行”或者同 artist 的歌曲。具体实现就是一条 SQL：查 song 表里 genre 相同但 id 不同的歌，按播放次数倒序取前 10 条。这种方案胜在逻辑简单、可解释性强，面试官问起来你会很清楚地说“我是基于歌曲标签做的召回”。

用户行为协同过滤则稍微高级一点，思路是“和你行为相似的人喜欢什么，就推给你”。实现分两步：第一步建一个用户-歌曲的评分矩阵，用播放次数和收藏记录作为隐式评分；第二步计算用户相似度，我采用的是余弦相似度公式。具体到 Java 实现，不用引入任何机器学习库，用 HashMap 维护矩阵，把计算过程写成普通工具类就行。下面这段逻辑描述的是核心思路：

java复制// 1. 构建“用户 -> 歌曲 -> 行为分值”的映射
Map<Long, Map<Long, Integer>> userSongScore = buildUserSongScore();
// 2. 计算目标用户与每个用户的余弦相似度
double similarity = cosineSimilarity(targetUserVector, otherUserVector);
// 3. 找出相似度最高的 K 个用户
// 4. 把相似用户喜欢但目标用户没听过的歌，按相似度加权汇总

新用户没有行为数据，这时候就退化成热门推荐，直接按全局播放量倒序出榜单。我把这种策略叫作“冷启动兜底”，就是代码里 if (userSongScore.get(userId) == null || userSongScore.get(userId).isEmpty()) 时走热门榜。这种多策略组合的设计思路，面试时讲出来比单纯背公式加分得多。顺手提一句，行为数据要定期清理或者做时效衰减，比如三个月前的播放记录权重打折，否则推荐列表越来越“陈旧”。

3.3 全局异常处理与统一响应结构

后端接口写得再认真，也免不了运行时异常，必须有一套统一处理机制。源码里处理得比较好的地方是加了 @RestControllerAdvice 全局异常处理器，配合自定义的 BusinessException，把业务错误和系统错误彻底分隔开。

java复制@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(BusinessException.class)
    public Result<Void> handleBusinessException(BusinessException e) {
        return Result.fail(e.getCode(), e.getMessage());
    }

    @ExceptionHandler(Exception.class)
    public Result<Void> handleException(Exception e) {
        log.error("系统异常", e);
        return Result.fail(500, "系统繁忙，请稍后再试");
    }
}

这样设计的直接好处是：前端 axios 拦截器只需要处理 code != 200 的情况统一弹出 message，后端不用在每个 controller 里写 try-catch，代码量下降一大截。另外日志一定要在全局异常里打印完整堆栈，否则线上排查问题全靠猜。我还见过一些项目把 SQL 异常原封不动返回给前端，连表名字段名都暴露了，这是很危险的做法，全局异常处理里务必要把底层异常转成通用提示。

4. 前端工程：Vue 环境、路由与播放器

4.1 Vue 项目初始化与依赖安装的版本坑

前端这块源码用的是 Vue 3 生态，构建工具是 Vite。第一次跑 Vue 项目的人最容易卡在环境配置上。我建议按下面这个顺序检查环境：先确认 Node.js 版本，Vue 3 + Vite 在 Node 16 以下会直接报错，推荐 18 以上的 LTS 版本；然后确认包管理器是用 npm 还是 pnpm，源码里如果带了 package-lock.json 就老实继续用 npm，如果带了 pnpm-lock.yaml 就优先用 pnpm，混着用容易产生依赖版本不一致。

依赖安装慢是个老生常谈的问题，npm install 卡半天，解决方案就是切到国内镜像源。执行 npm config set registry https://registry.npmmirror.com 之后，下载速度肉眼可见地提升。如果还是失败，优先看报错信息里的 ETIMEDOUT 还是 EACCES，前者基本是网络问题换镜像源，后者多半是权限问题，Windows 上可以用管理员终端重试。

还有一个高频坑就是 Vue 的 TypeScript 工程配了 extends: "@vue/tsconfig/tsconfig.web.json"，但项目里找不到这个包。这是因为 @vue/tsconfig 没有被正确安装，或者版本对不上。解决办法很直接：装这个依赖 npm install -D @vue/tsconfig，如果还有问题就检查 package.json 里的版本是否和官方文档一致。这类问题本质都是“依赖没装完整”或者“lock 文件版本落后”，先删 node_modules 和 lock 文件重装一遍，能解决 80% 的怪问题。

4.2 axios 封装与跨域联调

前端所有接口请求都走 axios，这是 Vue 项目的事实标准。源码里建议做一层轻量封装，把 baseURL、超时时间、请求拦截器、响应拦截器统一起来。

javascript复制import axios from 'axios'
import { useUserStore } from '@/stores/user'

const service = axios.create({
  baseURL: '/api',
  timeout: 10000
})

service.interceptors.request.use(config => {
  const token = useUserStore().token
  if (token) {
    config.headers.Authorization = `Bearer ${token}`
  }
  return config
})

service.interceptors.response.use(
  response => {
    const res = response.data
    if (res.code !== 200) {
      // 统一业务错误提示
      return Promise.reject(new Error(res.message))
    }
    return res.data
  },
  error => {
    // 401 情况跳登录页
    return Promise.reject(error)
  }
)

这里用到了 Pinia 状态管理（Vuex 的现代替代品），token 存在 userStore 里。页面刷新后 Pinia 内存数据会丢，所以要把 token 同步持久化到 localStorage，初始化 store 时再读回来。这个坑几乎每个 Vue 项目都会遇到，遗漏了就会“登录成功后刷新页面，状态就丢了”。

开发环境的跨域问题靠 Vite 的 proxy 解决，在 vite.config.js 里配置：

javascript复制server: {
  port: 5173,
  proxy: {
    '/api': {
      target: 'http://localhost:8080',
      changeOrigin: true
    }
  }
}

配好之后，前端写 /api/song/list，请求会转给 http://localhost:8080/api/song/list，浏览器里看不到任何跨域报错。注意后端 controller 的 RequestMapping 也要带 /api 前缀，或者后端加 context-path，保证两边路径拼接一致，这是联调最容易对不上的地方。

4.3 播放器组件与 m3u8 音频流的处理

播放器是音乐系统的门面，源码里用 audio 元素封装了一个全局播放器组件，加上封面旋转、歌词滚动、播放列表三个核心功能。全局播放器的核心点在于状态提升：播放状态、当前歌曲、播放进度不能散落在每个页面组件里，而是放进全局状态（Pinia），这样从歌单页点了一首歌，切到推荐页音乐还在接着放，这是“全局播放器”和“页面内播放器”的本质区别。

vue复制<template>
  <div class="player-bar" v-if="currentSong">
    <img :src="currentSong.coverUrl" :class="{ playing: isPlaying }" />
    <div class="info">
      <div class="title">{{ currentSong.title }}</div>
      <div class="artist">{{ currentSong.artist }}</div>
    </div>
    <audio
      ref="audioRef"
      :src="currentSong.fileUrl"
      @play="onPlay"
      @pause="onPause"
      @timeupdate="onTimeUpdate"
      @ended="onEnded"
    />
  </div>
</template>

音频文件格式方面，普通的 mp3、flac 直接给 audio 元素的 src 就能播。源码里我还看到支持 m3u8 格式的场景，m3u8 本质是 HLS 协议的索引文件，里面存的是分片视频/音频的 URL 列表，浏览器原生不支持直接播放，需要引入 hls.js 库。加载音频时判断一下文件后缀，遇到 .m3u8 就用 Hls.isSupported() 创建实例，把流绑定到 audio 元素上。

javascript复制if (fileUrl.endsWith('.m3u8') && Hls.isSupported()) {
  const hls = new Hls()
  hls.loadSource(fileUrl)
  hls.attachMedia(audioRef.value)
}

这里有个实践经验：m3u8 流播放时，拖动进度条会有明显的缓冲感，因为 HLS 是按分片加载的，不够流畅。本地练习项目建议直接用 mp3 文件测试，把 m3u8 的兼容逻辑保留在代码里即可。另外要提醒一点，封面旋转动画记得在 audio 的 pause 事件里暂停动画，否则用户暂停播放后封面还在转，看起来很诡异。Vue 组件通信还可以用插槽（slot）扩展播放器里的自定义按钮位，比如在播放器右侧放一个“下一首”插槽，不同页面传入不同的点击逻辑，这就是 Vue 插槽在实际项目里的典型用法。

5. 完整运行步骤：照着抄就能跑起来

5.1 数据库与后端启动

我按照“拿到源码到能听歌”的路径，把完整运行步骤整理出来，每一步都标注了对应文件的位置，避免新手在某个环节卡半小时。

第一步是准备环境。需要安装 JDK 17（如果源码基于 Spring Boot 3，JDK 8 直接无法运行）、Maven 3.6+、MySQL 5.7 或 8.0、Node.js 18+。环境是这套系统最容易出问题的地方，版本不匹配的错误提示往往非常抽象。

第二步是建库和导入数据。在 MySQL 中执行源码根目录下的 sql/music_db.sql 脚本：

bash复制mysql -u root -p < sql/music_db.sql

脚本会创建数据库、表结构和初始数据，包括几条测试歌曲和测试账号。手动执行脚本前可以先用 show databases 确认是否已有同名数据库，避免重复建表报错。

第三步是改后端配置。打开 backend/src/main/resources/application.yml，把数据库用户名、密码改成你自己的，确认文件上传目录存在：

yaml复制spring:
  datasource:
    url: jdbc:mysql://localhost:3306/music_db?useUnicode=true&characterEncoding=utf8mb4&serverTimezone=Asia/Shanghai
    username: root
    password: your_password

第四步是启动后端。在 backend 目录下执行：

bash复制mvn spring-boot:run

看到 Started Application in xxx seconds 的日志就说明后端起来了，可以先访问 http://localhost:8080/api/song/list 试试接口是否返回 JSON 数据。

5.2 前端启动与代理配置

后端跑起来后，进入 frontend 目录，依次执行：

bash复制npm install
npm run dev

第一次 npm install 时间会比较长，慢的话换个镜像源重试。启动成功后终端会显示 Local: http://localhost:5173/，浏览器打开就能看到登录页。源码里默认有测试账号，比如 admin / 123456，SQL 脚本里通常都会注入，直接登录即可。

前端跑起来后先不要急着点功能，先确认代理是否生效。按 F12 打开浏览器开发者工具，切到 Network 面板，随便发一个接口请求，看请求 URL 是不是以 /api 开头、响应状态是不是 200。如果看到 ERR_CONNECTION_REFUSED，说明后端没起来；如果看到 ERR_PROXY_CONNECTION_FAILED，说明 Vite 代理配了但目标地址不对，回 vite.config.js 检查 target 是否指向后端真实端口。

第一次登录后如果页面显示“请求失败”而不是“密码错误”，大概率是前后端路径前缀不一致的问题。比如后端接口是 /api/user/login，前端请求写成了 /user/login，代理带了 /api 前缀就会拼成 /api/user/login，看起来没问题；但如果你把前端请求写成 /api/user/login，代理层又自动加了一个 /api，就会变成 /api/api/user/login，4xx 错误直接安排。所以记住一个原则：前端代码里的请求路径不带 /api，让代理统一加。

5.3 打包部署到 Nginx

开发模式跑通之后，还需要知道怎么部署到生产环境，这是面试里“有没有真正上线经验”的分水岭题。前端的打包命令是：

bash复制npm run build

Vite 会生成 dist 目录，里面是纯静态文件。后端打包则是：

bash复制mvn clean package -DskipTests

生成 target/music-server.jar。部署时 Nginx 的配置可以这样写：

nginx复制server {
    listen 80;
    server_name your-domain.com;

    root /var/www/music-front;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location /api/ {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    location /files/ {
        proxy_pass http://127.0.0.1:8080;
    }
}

location / 里的 try_files 是 Vue Router 的 history 模式必备配置，否则刷新页面会 404。后端以 jar 方式运行：

bash复制nohup java -jar music-server.jar --server.port=8080 > music.log 2>&1 &

部署完成后，访问域名应该能看到系统页面，登录、播放、推荐功能全部正常。这一步做完，整个项目的“源码 + 运行步骤 + 计算机技术”三块就彻底闭环了。

6. 高频问题排查与避坑速查

6.1 Spring Boot 版本过高导致的老大难问题

很多拿到源码的人第一反应是：“我的 Spring Boot 版本是 3.x，怎么跑不起来？”这里有个核心知识点：Spring Boot 3.0 开始强制要求 JDK 17，而且把原来 javax.* 包下的所有 API 迁移到了 jakarta.*。如果你的 IDE 导入依赖后大量报红，先看报错内容里是 javax.servlet 还是 jakarta.servlet。

MyBatis-Plus 也要注意兼容性。旧版的 MyBatis-Plus（3.5.3 以下）不支持 Spring Boot 3，配套的 mybatis-plus-spring-boot3-starter 是新出的依赖，坐标里的 artifactId 都变了。对应关系我整理在下面：

如果你用的是 Spring Boot 3，JDK 版本还停留在 8，IDE 里启动会直接报 UnsupportedClassVersionError。这种时候别去强行改 pom 里的版本，先把 JDK 切换成 17 再重装依赖。遇到版本问题，我的排查顺序永远是：先看 JDK → 再看 starter 包 → 再看锁文件，版本相关的坑 90% 都能按这个顺序定位。

6.2 前后端联调三大症状

联调阶段最常见的三个问题，我从排查经验里总结成一个速查表：

第三个症状是联调里出现频率最高的，我见过太多人卡在这里。调试技巧是在后端日志里看 user-agent 和请求路径，确认实际收到的 URL 长什么样，然后再反推是哪一段拼接出了问题。另外后端 CORS 配置如果走代理模式，其实不需要额外开启跨域；但如果你绕开代理直接请求 http://localhost:8080，就必须在 Spring 里配置 CorsFilter 放行前端域名。

6.3 源码交付给别人的完整动作

“vue 项目源码怎么发给别人”这个问题看着简单，其实里面有不少注意事项。交付 Vue 项目源码前，必须有三件事：删掉 node_modules（这目录动辄几百 MB，而且每个人环境不同，依赖包必须重新安装）；确认 .gitignore 里有没有忽略 node_modules、dist、.env.local；检查 .env 文件里的数据库密码、JWT 密钥这类敏感配置是否被他人看到。

我的建议是：交付时直接打一个 zip 包，里面包含完整的后端代码、前端代码、SQL 脚本和一个 README.md。README 里写清楚 JDK/Node/MySQL 的版本要求、启动命令、默认账号密码、端口占用情况。拿到你源码的人按照 README 操作，如果五分钟内跑不起来，那就是 README 写得不合格。源码交付的本质是“环境标准化”，不是把代码扔过去就完事。

最后再分享一个实际体会：这套系统跑通之后，别急着结束项目。你可以给它加一个“最近播放”页面，或者把推荐算法从“相似用户”升级成“用户画像标签”，又或者把本地文件存储替换成云存储。每加一个功能，你对整个技术栈的理解就会加深一层。这几年我带过不少人用类似项目做毕设和简历项目，最后能讲得清楚、答得上追问的，一定是自己亲手改过的人，而不是只把源码跑通就算完成的人。