简介一套适用于Java专业毕业设计场景的校友录管理系统源码采用SpringBootVueMySQL组合实现前后端分离的校友信息管理功能。资源共384个文件压缩包14.39MB组成包括100个java文件后端服务逻辑、83个vue文件前端组件页面、40个js与19个css页面交互与样式另有sql数据库脚本、doc说明文档及多个配置文件目录划分清晰。系统拆分为前端client_code、管理端manage_code、服务端server_code三部分附带数据库表结构文档和部署说明开发环境涵盖JDK1.8及MySQL5.7能帮助快速完成环境搭建与流程理解。目前已有63人学习适合正在准备Java毕业设计或需要完整信息管理项目参考的学生。通过本项目可掌握SpringBoot框架配置、Vue组件化开发及MySQL数据持久化同时学习前后端分离架构的实际落地方式。1. 校友录管理系统源码springbootvuemysql拿到的第一件事先跑通登录链路校友录管理系统源码springbootvuemysql这类毕业设计拿到手最常见的坑不是看不懂业务代码而是三天内都起不来服务。前后端分离的工程不像单页面课设那么直白MySQL要建库导数据Spring Boot要用匹配的JDK和Maven启动Vue前端还得先把依赖装齐任何一环版本错位登录接口就一片红。这套系统能让你在一个完整业务里看到后端怎么写接口、前端怎么调接口、数据库表怎么设计是入门真实项目结构最划算的样本。接下来按真实操作顺序把解压、配置、启动、打包和排错全程过一遍。你手里的包结构可能略有不同但排错思路完全通用。2. 环境准备与项目结构先别碰代码把JDK/Node/MySQL三兄弟对齐2.1 拿到zip后先检查骨架文件布局、sql脚本与说明文档的读取顺序先把压缩包解压到没有中文和空格的路径里。我见过有人把项目放在“C:\Users\张三\桌面\毕设\校友录系统”下结果Maven打包直接报路径编码错误因为Windows控制台默认编码和Java的UTF-8对不上。解压后用tree或find命令看一眼整体结构。unzip alumni-system.zip -d alumni-system cd alumni-system find . -maxdepth 2 -type d | sort正常情况下你会看到backend或server、frontend或web、sql或database这三个目录外加一份说明文档。如果你的包只有一层目录那就用ls -la看隐藏文件确认有没有.git、.mvn这类文件。说明文档通常是word或md格式建议先读“环境需求”章节那上面写的JDK版本、MySQL版本就是作者当时的开发环境别一上来就用JDK17跑Spring Boot 2.x的项目后面全是编译错误。find -maxdepth 2会绕过node_modules和target目录里的深层文件快速暴露顶层结构。如果系统里没有unzipWindows直接右键解压Linux用sudo apt install unzip装上即可。读说明文档时我一般会拿笔记三个信息SQL脚本文件名、后端启动端口、前端启动端口。这三个值决定后面所有配置要往哪里改比业务逻辑重要得多。2.2 版本对齐表JDK8/17、Maven和Node版本与Vue项目的匹配关系校友录系统最典型的技术栈是Spring Boot 2.x Vue 2.x MySQL 5.7但也有人用Spring Boot 3.x Vue 3。版本不匹配会直接导致启动失败比如Spring Boot 3把javax包换成jakarta老代码里import javax.servlet会直接编译不过。所以开工前先确认三件事后端pom.xml里的parent版本、前端package.json里的vue版本以及你机器上的JDK版本。组件推荐搭配踩坑提示JDKSpring Boot 2.x用JDK8Spring Boot 3.x用JDK17JDK17跑老项目会报UnsupportedClassVersionErrorMaven3.6.3及以上建议3.8.x3.9强制更高JDK版本JDK8可能跑不了NodeVue 2配Node 14/16Vue 3配Node 16/18Node 20跑老Vue项目常出OpenSSL错误MySQL5.7或8.0字符集utf8mb48.0的时间戳与时区默认值会引发时区报错这张表不是拍脑袋写的。Maven 3.9需要JDK 8但如果你用JDK8跑3.9.0会提示“Unsupported major version”Node 20里的OpenSSL 3对老版本webpack不兼容会报ERR_OSSL_EVP_UNSUPPORTED。所以我一般会先跑一遍环境检查命令再决定是否要装指定版本而不是直接改代码。如果手里只有新版JDK可以临时改pom.xml里的java.version但Spring Boot 2.x和JDK17的兼容性问题不止版本号一处javax.annotation.PostConstruct在JDK11后被移除老代码会报找不到类。与其打补丁不如直接装一个JDK8。Linux/macOS可以用SDKMAN快速安装Windows手动装一个绿色版也能用。2.3 四条命令验证环境java -version、mvn -v、npm -v、mysql --version花30秒跑四条命令能把一半的启动失败拦在门外。java -version mvn -v npm -v mysql --versionjava -version会打印类似openjdk version 1.8.0_392mvn -v第一行是Maven版本后面跟的是它运行时用的Java版本注意看是否和你java -version一致如果Maven用的是另一个JDK说明JAVA_HOME没设对。npm -v只需要一个版本号比如10.2.4但如果前端项目是Vue 2请降级Node 16再跑。mysql --version会显示mysql Ver 14.14 Distrib 5.7.44这里的5.7版本对应官方Windows安装包常见版本。如果某条命令报“不是内部或外部命令”说明环境变量没配好。Windows用户在“系统属性-环境变量”里把JAVA_HOME指到JDK安装目录再把%JAVA_HOME%\bin加进PathNode和MySQL安装时勾选“Add to PATH”即可。这些命令没问题后才开始碰源码。2.4 版本临时切换三件套SDKMAN、nvm、MySQL实例选择当你确实不想卸载现有版本时可以按项目隔离运行时。# Linux/macOS: 用 SDKMAN 切换 JDK curl -s https://get.sdkman.io | bash source $HOME/.sdkman/bin/sdkman-init.sh sdk install java 8.0.392-tem sdk use java 8.0.392-temcurl ... | bash的写法是SDKMAN官方推荐执行后在同一终端里临时使用JDK8重启终端后回到默认版本。前端同理Node版本用nvm管理。# 安装并临时切换到 Node 16 nvm install 16.20.2 nvm use 16.20.2nvm在Windows下用nvm-windowsmacOS和Linux直接按官方命令装。MySQL如果装了多个版本连接时要显式指定端口比如5.7默认3306、8.0默认3307在application.yml的url里写对应端口即可。这些切换工具是毕设答辩前临时救场用的要提前在真机上演练一遍别在评委面前表演翻车。3. 后端跑通Spring Boot的建库脚本、数据源配置与登录接口验证3.1 先把SQL脚本导入MySQL建库顺序与utf8mb4存储中文的坑后端启动第一步不是mvn spring-boot:run而是把数据库建好。校友录系统至少会有三张核心表校友信息表、用户表、班级表。如果脚本里没有CREATE DATABASE语句就需要先手动建库再导入。常见的做法是把SQL文件交给MySQL命令行执行。mysql -uroot -p sql/alumni.sql如果担心密码暴露在历史记录里可以省略-p后回车再输入。执行成功后进MySQL确认mysql -uroot -p use alumni_db; show tables;show tables;会列出所有表名重点看alumni、user、class这几张表都在不在。如果show tables为空多半是SQL文件里没有use语句导入到了默认库。解决方案是打开SQL文件在开头补上USE alumni_db;再重新导入。中文乱码的坑一般出现在Windows下用手写编辑器打开SQL再导入的场景。如果表创建时用的字符集是latin1插入中文后显示问号。预防方法有两种一是导入前在mysql客户端执行SET NAMES utf8mb4;二是建库时直接指定字符集。推荐用后者一劳永逸。CREATE DATABASE IF NOT EXISTS alumni_db DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;utf8mb4能存emoji和生僻字utf8在MySQL 8里实际是utf8mb3覆盖不到四字节字符。校友录里如果有人在留言墙里放了个emoji用utf8就会报“Incorrect string value”。另外MySQL 5.7不支持utf8mb4_0900_ai_ci排序规则所以建表语句里指定utf8mb4_general_ci最稳兼容两个版本。3.2 修改application.yml数据源url参数、密码特殊字符、mybatis驼峰映射数据库导入完成后打开后端src/main/resources/application.yml。典型结构长这样server: port: 8080 spring: datasource: url: jdbc:mysql://localhost:3306/alumni_db?useUnicodetruecharacterEncodingutf8useSSLfalseserverTimezoneAsia/Shanghai username: root password: 1#2$3%4 driver-class-name: com.mysql.cj.jdbc.Driver jackson: time-zone: Asia/Shanghai mybatis: mapper-locations: classpath:mapper/*.xml configuration: map-underscore-to-camel-case: trueurl里的四个参数各有用途。useUnicodetruecharacterEncodingutf8保证中文按UTF-8传输useSSLfalse关掉SSL握手本地开发省去证书问题serverTimezoneAsia/Shanghai解决MySQL 8的时区报错如果你的MySQL是8.0还要补allowPublicKeyRetrievaltrue否则启动时报公钥获取错误。driver-class-name用com.mysql.cj.jdbc.Driver老项目里如果写的是com.mysql.jdbc.Driver在MySQL 8下会有警告建议顺手改成新驱动。密码这一列经常翻车。如果密码里有、、?这类符号Spring Boot读取时会把当成参数连接符导致连不上库。最稳妥的办法是像上面一样给整段密码加单引号。改完配置后先只启动后端看能不能连上库再谈接口。如果要兼容两个版本的MySQL可以在pom.xml里显式指定驱动版本dependency groupIdmysql/groupId artifactIdmysql-connector-java/artifactId version8.0.33/version /dependency8.0.33是一个长期维护的驱动版本兼容MySQL 5.7和8.0。这里不需要改别的东西驱动会自动检测服务端版本。3.3 启动后端并用curl验证登录接口启动日志、404与401的含义启动命令很简单cd backend mvn clean install -DskipTests mvn spring-boot:run-DskipTests跳过测试用例防止因为环境问题卡在测试阶段。第一次执行会下载大量依赖如果卡在一个百分比不动多半是中央仓库慢需要到~/.m2/settings.xml里配置镜像。具体操作放在后面避坑章节。后端起来后日志里出现Tomcat started on port(s): 8080且没有异常堆栈说明这一环已经通了。接下来用一个登录接口做验证。校友录系统的登录接口路径通常是/api/auth/login但不同源码可能写成/api/user/login具体以说明文档或Controller为准。curl -X POST http://localhost:8080/api/auth/login \ -H Content-Type: application/json \ -d {username:admin,password:123456}正常会返回一段JSON里面带token和用户信息。如果提示404先检查Controller里的RequestMapping前缀和这里的路径是否一致。如果返回401/403优先看密码是否正确以及数据库里admin用户的密码是不是MD5加密存储的。很多毕设源码默认把密码表里的值存成MD5直接传明文会匹配不上。解决方式要么把数据库里改成MD5要么在前端登录时做MD5加密这取决于后端UserService里的校验逻辑。如果说明文档里写了Swagger访问http://localhost:8080/swagger-ui.html或http://localhost:8080/swagger-ui/index.html就能看到接口列表。但并不是所有毕设都集成了Swagger没有也可以直接用curl验证登录即可。这一步跑通说明后端、数据库、接口三者已经咬合。3.4 用IDEA导入后端JDK指定、Lombok插件与启动类配置很多人喜欢用命令行启动但调试时还是IDEA方便。导入时不要直接双击pom.xml文件而是用IDEA的“Open”选择pom.xml所在目录等Maven自动加载依赖。加载完成后打开File - Project Structure - Project把Project SDK选成和之前环境检查一致的JDK版本。如果项目里大量使用Data注解说明依赖了Lombok。命令行运行不受影响但IDEA调试时需要安装Lombok插件并开启Enable annotation processing否则启动类直接报“找不到符号getXxx()”。这个坑在毕设源码里出现频率极高因为作者是在自己装过插件的机器上开发的代码本身没问题换一台机器就翻车。运行后端前还要确保数据库服务已经启动。IDEA底部有一个“Services”窗口点击“Add Service”可以挂载MySQL但初学者建议直接用命令行net start mysql或其他系统原生的服务管理方式避免被IDEA的数据库工具误导。启动后端时在Run Configuration里找到AlumniApplication这个类右键Run。启动后看控制台输出如果最后一行是Started AlumniApplication后端就绪。4. 前端Vue部分依赖安装、代理转发与登录调通4.1 npm install的三种结局node-sass失败、版本不匹配、安装成功前端通常是一个Vue项目。先看frontend/package.json里scripts段中的dev或serve命令确认依赖要求。然后装依赖cd frontend npm install这一步有三类结果。第一类是安装成功不需要额外处理。第二类是node-sass相关报错比如Node Sass does not support your current environment。原因是node-sass是C模块需要针对当前Node版本重新编译Node版本太高或太低都会失败。处理方案是删掉旧依赖改用dart-sass。npm uninstall node-sass npm install sass1.32.13 --save-dev第三类是npm ERR! ERESOLVE unable to resolve dependency tree一般出现在新npm对老项目的依赖树校验过严。解决方式是指定legacy模式安装。npm install --legacy-peer-deps--legacy-peer-deps的作用是跳过peer依赖的严格校验按旧版npm的行为去处理依赖。这是对付老项目的常用逃生门但不建议用在生产环境。如果npm install卡在sass_binary_site下载可以给npm设置镜像源。npm config set registry https://registry.npm.taobao.org npm config set sass_binary_site https://npm.taobao.org/mirrors/node-sass注意这是淘宝源技术圈公开的常用加速点只是把下载地址指向国内镜像。如果项目里有yarn.lock建议只用yarn安装yarn install混用npm和yarn会生成两套锁文件后续提交代码时会冲突这个问题在小组合作时尤其浪费时间。4.2 vue.config.js里的devServer代理让前端页面的/api请求打到8080前后端分离时前端开发服务器默认在localhost:3000或localhost:8081直接向后端发起跨域请求会被浏览器拦截。最常见也是毕设里最推荐的做法是在vue.config.js里配一个代理。module.exports { devServer: { port: 3000, proxy: { /api: { target: http://localhost:8080, changeOrigin: true } } } }这段配置的意思是把所有以/api开头的请求转发到http://localhost:8080并且把请求头里的Host改成目标地址让后端以为自己接收的是同源请求。port: 3000可以按需改成8081等没被占用的端口。配置之后前端代码里请求路径写成/api/auth/login浏览器访问的是http://localhost:3000/api/auth/login实际打到的是http://localhost:8080/api/auth/login。如果代理没有生效先确认vue.config.js是否在项目根目录并且项目不是用Vite构建的。Vite项目的代理配置在vite.config.js里写法完全不同。// vite.config.js export default defineConfig({ server: { port: 3000, proxy: { /api: { target: http://localhost:8080, changeOrigin: true } } } })区分vue-cli和Vite的办法是看package.json里的devDependencies有没有vue/cli-service有就是webpack架构用vue.config.js有vite则用vite.config.js。很多校友录源码的前端是老一辈vue-cli脚手架但也有新版本换成Vite配置错位置会白耗一下午。如果需要代理多个接口前缀比如/api和/file可以并列写多个入口但每个都指向同一个target。不想写那么多的话也可以把后端接口统一加/api前缀最省事。4.3 启动页面与登录调通npm run serve、浏览器访问与Network面板依赖装好、代理配好后启动前端。npm run serve启动日志会出现App running at: Local: http://localhost:3000/。打开浏览器访问这个地址用admin/123456登录。如果页面一直转圈按F12打开开发者工具切到Network面板刷新一下登录请求。点击那个auth/login请求看它在“Preview”标签里返回什么。如果返回{code:500,msg:Request method GET not supported}说明请求方法用错了前端axios没有按post发出。如果返回401 Unauthorized说明用户名密码不对或请求头缺了token。还有一种经典情况前端登录成功但个人信息一直加载不出来。这时看Network里有没有一条校友列表请求返回403多半是token没被放进请求头。检查前端封装的axios拦截器里有没有这样一段逻辑从localStorage拿token并设置到Authorization头。如果没有就补上。// request.js 拦截器 axios.interceptors.request.use(config { const token localStorage.getItem(token) if (token) { config.headers.Authorization Bearer token } return config })这段代码在几乎所有校友录系统里都有只是写法不同。加完重启前端再试试查看校友列表、添加一条记录看数据能不能写进MySQL。能跑通说明前端到后端再到数据库这条链路已经完全打通。到这一步“能登录”这个最小闭环就成立了。如果登录后页面跳转正常但刷新又回到登录页大概率是localStorage没被保存或者路由守卫判断token的逻辑不对。路由守卫通常在src/router/index.js里检查是不是用localStorage.getItem(token)来判断而不是用响应式对象的某个属性后者刷新后必然丢失。另外很多毕设前端用Element UI登录表单里会有校验规则如果字段名和后端不一致会报“用户名不能为空”但实际输入了。这种情况优先看rules里的prop和v-model绑定的字段名是否一致。这个小问题能让新手白白怀疑半小时后端接口。5. 避坑/常见问题/排查让校友录源码稳定运行的5条血泪记录5.1 8080端口被占用导致后端启动失败找到进程与换端口现象mvn spring-boot:run启动到一半日志里出现Port 8080 was already in use或APPLICATION FAILED TO START。原因本机某个进程已经占了8080可能是另一个Java进程、Tomcat或者调试工具。解决先找占用者再决定杀还是换。# Windows netstat -ano | findstr :8080 taskkill /PID pid /F # Linux/macOS lsof -i :8080 kill -9 pid如果不想杀进程也可以在application.yml里把server.port改成8081同时记得把前端代理的target改成http://localhost:8081。毕业设计演示时经常需要同时开多个项目端口冲突是第一事故点先排练一遍能省很多事。5.2 MySQL 8的Public Key Retrieval报错和时区报错url参数补齐现象后端启动时数据源初始化报Public Key Retrieval is not allowed for this user或者The server time zone value Öйú±ê׼ʱ¼ä is unrecognized。原因MySQL 8默认的caching_sha2_password认证插件要求客户端在首次连接时获取服务器公钥而serverTimezone没设置时驱动会去读系统时区中文名导致乱码报错。解决在application.yml的url里补两个参数。url: jdbc:mysql://localhost:3306/alumni_db?useUnicodetruecharacterEncodingutf8useSSLfalseserverTimezoneAsia/ShanghaiallowPublicKeyRetrievaltrueallowPublicKeyRetrievaltrue专门解决公钥获取问题。如果用的是MySQL5.7则不需要这个参数。另外可以在数据库侧设置全局时区。SET GLOBAL time_zone 08:00;改完后重启MySQL再重启后端。如果还报Unknown database alumni_db检查是不是建库脚本没执行成功回到第3章重新确认。5.3 Maven依赖下载卡死或报Could not transfer artifact换镜像与清理lastUpdated现象mvn clean install停在Downloading: ...很长时间最后报Could not transfer artifact org.springframework.boot:spring-boot-starter-parent:...。原因默认的Maven中央仓库在部分网络环境下不稳定下载中断后留下.lastUpdated标记文件导致后续即使网络恢复也会直接跳过下载。解决在~/.m2/settings.xml中配置一个公共镜像并清掉本地仓库中损坏的缓存文件。mirrors mirror idaliyun/id mirrorOfcentral/mirrorOf urlhttps://maven.aliyun.com/repository/public/url /mirror /mirrors清缓存最简单的方法是定位到报错的那个依赖把~/.m2/repository下对应目录里的.lastUpdated删掉再重新运行mvn -U强制更新。-U参数会强制检查远程仓库是否有新版本避免本地缓存误导。如果全盘清空本地仓库下次要全部重新下载不建议。5.4 前端登录接口跨域报错或请求没到后端验证代理路径与axios baseURL现象浏览器Network里登录接口直接显示Failed to fetch或后端日志里完全没有收到请求有的是提示CORS policy: No Access-Control-Allow-Origin。原因前端请求路径没走代理或者代理配置只对/api生效但实际接口路径是/auth/login没带/api前缀。也可能axios设置了完整的baseURL比如http://localhost:8080导致代理被绕过。解决先看Network里请求的完整URL。如果显示的是http://localhost:3000/auth/login说明代理没匹配到因为代理规则写的是/api。两个办法要么把请求路径改成以/api开头要么放宽代理匹配规则。proxy: { /api: { target: http://localhost:8080, changeOrigin: true }, /auth: { target: http://localhost:8080, changeOrigin: true } }如果后端真开了跨域限制也可以在Spring Boot侧加一个CORS配置类但毕设里最推荐只用开发代理。因为代理一旦配好浏览器看到的请求是同源的根本不存在跨域。若是Vite项目还要注意.env.development里VITE_API_BASE应设为/api否则环境变量里的完整地址会绕过代理直连后端导致CORS又回来。5.5 打包后页面空白或刷新404前端路由history模式需要后端配合现象本地npm run serve一切正常但执行npm run build后把dist目录放到Nginx或Tomcat下访问首页白屏刷新某个路径直接404。原因Vue Router默认用hash模式路径里有#刷新不会404。但如果源码里改成了history模式刷新/alumni/detail/1时服务器找不到这个文件路径就会返回404如果部署到子路径还会白屏因为静态资源引用路径没带子路径前缀。解决先看src/router/index.js里mode是hash还是history。毕设演示用hash最省事不用改服务器。如果坚持用history就必须在nginx的location块里配置try_files。location / { root /usr/share/nginx/html/alumni; index index.html; try_files $uri $uri/ /index.html; }try_files的作用是当URL路径确实不存在时把请求回退到index.html让前端路由接管。如果用的是Tomcat则需要在web.xml里配置ErrorPage指向index.html顺手再确认publicPath是否为./或子路径。打包后的dist/index.html里引用JS和CSS的路径要是相对路径不然部署到二级目录又会白屏。这条是所有前后端分离项目上线的通用坑校友录系统也不例外。6. 进阶验证与调试技巧从“能跑”到“敢答辩”6.1 三个真实业务动作验证系统可靠性登录跑通只是起点。我会在答辩前用三个动作做回归验证。第一在页面上新增一位校友填写姓名、班级、电话保存后刷新页面确认数据还在。这一步验证MySQL写入与查询。第二修改当前用户密码退出后用新密码重新登录确认修改接口生效。第三步在班级列表页删除一个班级如果校友信息里还引用着这个班级看系统有没有提示“删除失败”而不是直接崩溃。这三个动作覆盖了前后端、数据库关系和异常处理比看一遍代码更能暴露隐藏问题。6.2 给校友录加一个ECharts统计图表从看懂接口到扩展接口如果还想做点亮点不妨把“班级人数统计”做成图表。先在后端写一个统计接口返回班级和人数列表前端用axios调这个接口再引入ECharts渲染。这个过程本质上是在复刻系统的核心开发流程建表、写SQL、写Mapper、暴露Controller、前端调用。完成以后你对这套源码的理解深度会超过大多数照着改参数的同学。最后说一个我自己的教训。刚拿到这类毕设源码的时候我总喜欢先改页面标题和颜色觉得换个主题就是自己的作品。后来发现真正难的不是改界面而是把启动过程中的每个日志都看明白。养成的习惯是每启动一个环节就完整截图一段启动日志端口、版本、报错行号都对一遍。这样做之后五分钟内能定位的故障越来越多。希望帮到你。本文还有配套的精品资源点击获取 
长河君 · 2026/10/10 10:38:37 · 阅读 1.2k SpringBoot+Vue+MySQL校友录系统：从环境配置到登录排错全攻略
简介一套适用于Java专业毕业设计场景的校友录管理系统源码采用SpringBootVueMySQL组合实现前后端分离的校友信息管理功能。资源共384个文件压缩包14.39MB组成包括100个java文件后端服务逻辑、83个vue文件前端组件页面、40个js与19个css页面交互与样式另有sql数据库脚本、doc说明文档及多个配置文件目录划分清晰。系统拆分为前端client_code、管理端manage_code、服务端server_code三部分附带数据库表结构文档和部署说明开发环境涵盖JDK1.8及MySQL5.7能帮助快速完成环境搭建与流程理解。目前已有63人学习适合正在准备Java毕业设计或需要完整信息管理项目参考的学生。通过本项目可掌握SpringBoot框架配置、Vue组件化开发及MySQL数据持久化同时学习前后端分离架构的实际落地方式。1. 校友录管理系统源码springbootvuemysql拿到的第一件事先跑通登录链路校友录管理系统源码springbootvuemysql这类毕业设计拿到手最常见的坑不是看不懂业务代码而是三天内都起不来服务。前后端分离的工程不像单页面课设那么直白MySQL要建库导数据Spring Boot要用匹配的JDK和Maven启动Vue前端还得先把依赖装齐任何一环版本错位登录接口就一片红。这套系统能让你在一个完整业务里看到后端怎么写接口、前端怎么调接口、数据库表怎么设计是入门真实项目结构最划算的样本。接下来按真实操作顺序把解压、配置、启动、打包和排错全程过一遍。你手里的包结构可能略有不同但排错思路完全通用。2. 环境准备与项目结构先别碰代码把JDK/Node/MySQL三兄弟对齐2.1 拿到zip后先检查骨架文件布局、sql脚本与说明文档的读取顺序先把压缩包解压到没有中文和空格的路径里。我见过有人把项目放在“C:\Users\张三\桌面\毕设\校友录系统”下结果Maven打包直接报路径编码错误因为Windows控制台默认编码和Java的UTF-8对不上。解压后用tree或find命令看一眼整体结构。unzip alumni-system.zip -d alumni-system cd alumni-system find . -maxdepth 2 -type d | sort正常情况下你会看到backend或server、frontend或web、sql或database这三个目录外加一份说明文档。如果你的包只有一层目录那就用ls -la看隐藏文件确认有没有.git、.mvn这类文件。说明文档通常是word或md格式建议先读“环境需求”章节那上面写的JDK版本、MySQL版本就是作者当时的开发环境别一上来就用JDK17跑Spring Boot 2.x的项目后面全是编译错误。find -maxdepth 2会绕过node_modules和target目录里的深层文件快速暴露顶层结构。如果系统里没有unzipWindows直接右键解压Linux用sudo apt install unzip装上即可。读说明文档时我一般会拿笔记三个信息SQL脚本文件名、后端启动端口、前端启动端口。这三个值决定后面所有配置要往哪里改比业务逻辑重要得多。2.2 版本对齐表JDK8/17、Maven和Node版本与Vue项目的匹配关系校友录系统最典型的技术栈是Spring Boot 2.x Vue 2.x MySQL 5.7但也有人用Spring Boot 3.x Vue 3。版本不匹配会直接导致启动失败比如Spring Boot 3把javax包换成jakarta老代码里import javax.servlet会直接编译不过。所以开工前先确认三件事后端pom.xml里的parent版本、前端package.json里的vue版本以及你机器上的JDK版本。组件推荐搭配踩坑提示JDKSpring Boot 2.x用JDK8Spring Boot 3.x用JDK17JDK17跑老项目会报UnsupportedClassVersionErrorMaven3.6.3及以上建议3.8.x3.9强制更高JDK版本JDK8可能跑不了NodeVue 2配Node 14/16Vue 3配Node 16/18Node 20跑老Vue项目常出OpenSSL错误MySQL5.7或8.0字符集utf8mb48.0的时间戳与时区默认值会引发时区报错这张表不是拍脑袋写的。Maven 3.9需要JDK 8但如果你用JDK8跑3.9.0会提示“Unsupported major version”Node 20里的OpenSSL 3对老版本webpack不兼容会报ERR_OSSL_EVP_UNSUPPORTED。所以我一般会先跑一遍环境检查命令再决定是否要装指定版本而不是直接改代码。如果手里只有新版JDK可以临时改pom.xml里的java.version但Spring Boot 2.x和JDK17的兼容性问题不止版本号一处javax.annotation.PostConstruct在JDK11后被移除老代码会报找不到类。与其打补丁不如直接装一个JDK8。Linux/macOS可以用SDKMAN快速安装Windows手动装一个绿色版也能用。2.3 四条命令验证环境java -version、mvn -v、npm -v、mysql --version花30秒跑四条命令能把一半的启动失败拦在门外。java -version mvn -v npm -v mysql --versionjava -version会打印类似openjdk version 1.8.0_392mvn -v第一行是Maven版本后面跟的是它运行时用的Java版本注意看是否和你java -version一致如果Maven用的是另一个JDK说明JAVA_HOME没设对。npm -v只需要一个版本号比如10.2.4但如果前端项目是Vue 2请降级Node 16再跑。mysql --version会显示mysql Ver 14.14 Distrib 5.7.44这里的5.7版本对应官方Windows安装包常见版本。如果某条命令报“不是内部或外部命令”说明环境变量没配好。Windows用户在“系统属性-环境变量”里把JAVA_HOME指到JDK安装目录再把%JAVA_HOME%\bin加进PathNode和MySQL安装时勾选“Add to PATH”即可。这些命令没问题后才开始碰源码。2.4 版本临时切换三件套SDKMAN、nvm、MySQL实例选择当你确实不想卸载现有版本时可以按项目隔离运行时。# Linux/macOS: 用 SDKMAN 切换 JDK curl -s https://get.sdkman.io | bash source $HOME/.sdkman/bin/sdkman-init.sh sdk install java 8.0.392-tem sdk use java 8.0.392-temcurl ... | bash的写法是SDKMAN官方推荐执行后在同一终端里临时使用JDK8重启终端后回到默认版本。前端同理Node版本用nvm管理。# 安装并临时切换到 Node 16 nvm install 16.20.2 nvm use 16.20.2nvm在Windows下用nvm-windowsmacOS和Linux直接按官方命令装。MySQL如果装了多个版本连接时要显式指定端口比如5.7默认3306、8.0默认3307在application.yml的url里写对应端口即可。这些切换工具是毕设答辩前临时救场用的要提前在真机上演练一遍别在评委面前表演翻车。3. 后端跑通Spring Boot的建库脚本、数据源配置与登录接口验证3.1 先把SQL脚本导入MySQL建库顺序与utf8mb4存储中文的坑后端启动第一步不是mvn spring-boot:run而是把数据库建好。校友录系统至少会有三张核心表校友信息表、用户表、班级表。如果脚本里没有CREATE DATABASE语句就需要先手动建库再导入。常见的做法是把SQL文件交给MySQL命令行执行。mysql -uroot -p sql/alumni.sql如果担心密码暴露在历史记录里可以省略-p后回车再输入。执行成功后进MySQL确认mysql -uroot -p use alumni_db; show tables;show tables;会列出所有表名重点看alumni、user、class这几张表都在不在。如果show tables为空多半是SQL文件里没有use语句导入到了默认库。解决方案是打开SQL文件在开头补上USE alumni_db;再重新导入。中文乱码的坑一般出现在Windows下用手写编辑器打开SQL再导入的场景。如果表创建时用的字符集是latin1插入中文后显示问号。预防方法有两种一是导入前在mysql客户端执行SET NAMES utf8mb4;二是建库时直接指定字符集。推荐用后者一劳永逸。CREATE DATABASE IF NOT EXISTS alumni_db DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;utf8mb4能存emoji和生僻字utf8在MySQL 8里实际是utf8mb3覆盖不到四字节字符。校友录里如果有人在留言墙里放了个emoji用utf8就会报“Incorrect string value”。另外MySQL 5.7不支持utf8mb4_0900_ai_ci排序规则所以建表语句里指定utf8mb4_general_ci最稳兼容两个版本。3.2 修改application.yml数据源url参数、密码特殊字符、mybatis驼峰映射数据库导入完成后打开后端src/main/resources/application.yml。典型结构长这样server: port: 8080 spring: datasource: url: jdbc:mysql://localhost:3306/alumni_db?useUnicodetruecharacterEncodingutf8useSSLfalseserverTimezoneAsia/Shanghai username: root password: 1#2$3%4 driver-class-name: com.mysql.cj.jdbc.Driver jackson: time-zone: Asia/Shanghai mybatis: mapper-locations: classpath:mapper/*.xml configuration: map-underscore-to-camel-case: trueurl里的四个参数各有用途。useUnicodetruecharacterEncodingutf8保证中文按UTF-8传输useSSLfalse关掉SSL握手本地开发省去证书问题serverTimezoneAsia/Shanghai解决MySQL 8的时区报错如果你的MySQL是8.0还要补allowPublicKeyRetrievaltrue否则启动时报公钥获取错误。driver-class-name用com.mysql.cj.jdbc.Driver老项目里如果写的是com.mysql.jdbc.Driver在MySQL 8下会有警告建议顺手改成新驱动。密码这一列经常翻车。如果密码里有、、?这类符号Spring Boot读取时会把当成参数连接符导致连不上库。最稳妥的办法是像上面一样给整段密码加单引号。改完配置后先只启动后端看能不能连上库再谈接口。如果要兼容两个版本的MySQL可以在pom.xml里显式指定驱动版本dependency groupIdmysql/groupId artifactIdmysql-connector-java/artifactId version8.0.33/version /dependency8.0.33是一个长期维护的驱动版本兼容MySQL 5.7和8.0。这里不需要改别的东西驱动会自动检测服务端版本。3.3 启动后端并用curl验证登录接口启动日志、404与401的含义启动命令很简单cd backend mvn clean install -DskipTests mvn spring-boot:run-DskipTests跳过测试用例防止因为环境问题卡在测试阶段。第一次执行会下载大量依赖如果卡在一个百分比不动多半是中央仓库慢需要到~/.m2/settings.xml里配置镜像。具体操作放在后面避坑章节。后端起来后日志里出现Tomcat started on port(s): 8080且没有异常堆栈说明这一环已经通了。接下来用一个登录接口做验证。校友录系统的登录接口路径通常是/api/auth/login但不同源码可能写成/api/user/login具体以说明文档或Controller为准。curl -X POST http://localhost:8080/api/auth/login \ -H Content-Type: application/json \ -d {username:admin,password:123456}正常会返回一段JSON里面带token和用户信息。如果提示404先检查Controller里的RequestMapping前缀和这里的路径是否一致。如果返回401/403优先看密码是否正确以及数据库里admin用户的密码是不是MD5加密存储的。很多毕设源码默认把密码表里的值存成MD5直接传明文会匹配不上。解决方式要么把数据库里改成MD5要么在前端登录时做MD5加密这取决于后端UserService里的校验逻辑。如果说明文档里写了Swagger访问http://localhost:8080/swagger-ui.html或http://localhost:8080/swagger-ui/index.html就能看到接口列表。但并不是所有毕设都集成了Swagger没有也可以直接用curl验证登录即可。这一步跑通说明后端、数据库、接口三者已经咬合。3.4 用IDEA导入后端JDK指定、Lombok插件与启动类配置很多人喜欢用命令行启动但调试时还是IDEA方便。导入时不要直接双击pom.xml文件而是用IDEA的“Open”选择pom.xml所在目录等Maven自动加载依赖。加载完成后打开File - Project Structure - Project把Project SDK选成和之前环境检查一致的JDK版本。如果项目里大量使用Data注解说明依赖了Lombok。命令行运行不受影响但IDEA调试时需要安装Lombok插件并开启Enable annotation processing否则启动类直接报“找不到符号getXxx()”。这个坑在毕设源码里出现频率极高因为作者是在自己装过插件的机器上开发的代码本身没问题换一台机器就翻车。运行后端前还要确保数据库服务已经启动。IDEA底部有一个“Services”窗口点击“Add Service”可以挂载MySQL但初学者建议直接用命令行net start mysql或其他系统原生的服务管理方式避免被IDEA的数据库工具误导。启动后端时在Run Configuration里找到AlumniApplication这个类右键Run。启动后看控制台输出如果最后一行是Started AlumniApplication后端就绪。4. 前端Vue部分依赖安装、代理转发与登录调通4.1 npm install的三种结局node-sass失败、版本不匹配、安装成功前端通常是一个Vue项目。先看frontend/package.json里scripts段中的dev或serve命令确认依赖要求。然后装依赖cd frontend npm install这一步有三类结果。第一类是安装成功不需要额外处理。第二类是node-sass相关报错比如Node Sass does not support your current environment。原因是node-sass是C模块需要针对当前Node版本重新编译Node版本太高或太低都会失败。处理方案是删掉旧依赖改用dart-sass。npm uninstall node-sass npm install sass1.32.13 --save-dev第三类是npm ERR! ERESOLVE unable to resolve dependency tree一般出现在新npm对老项目的依赖树校验过严。解决方式是指定legacy模式安装。npm install --legacy-peer-deps--legacy-peer-deps的作用是跳过peer依赖的严格校验按旧版npm的行为去处理依赖。这是对付老项目的常用逃生门但不建议用在生产环境。如果npm install卡在sass_binary_site下载可以给npm设置镜像源。npm config set registry https://registry.npm.taobao.org npm config set sass_binary_site https://npm.taobao.org/mirrors/node-sass注意这是淘宝源技术圈公开的常用加速点只是把下载地址指向国内镜像。如果项目里有yarn.lock建议只用yarn安装yarn install混用npm和yarn会生成两套锁文件后续提交代码时会冲突这个问题在小组合作时尤其浪费时间。4.2 vue.config.js里的devServer代理让前端页面的/api请求打到8080前后端分离时前端开发服务器默认在localhost:3000或localhost:8081直接向后端发起跨域请求会被浏览器拦截。最常见也是毕设里最推荐的做法是在vue.config.js里配一个代理。module.exports { devServer: { port: 3000, proxy: { /api: { target: http://localhost:8080, changeOrigin: true } } } }这段配置的意思是把所有以/api开头的请求转发到http://localhost:8080并且把请求头里的Host改成目标地址让后端以为自己接收的是同源请求。port: 3000可以按需改成8081等没被占用的端口。配置之后前端代码里请求路径写成/api/auth/login浏览器访问的是http://localhost:3000/api/auth/login实际打到的是http://localhost:8080/api/auth/login。如果代理没有生效先确认vue.config.js是否在项目根目录并且项目不是用Vite构建的。Vite项目的代理配置在vite.config.js里写法完全不同。// vite.config.js export default defineConfig({ server: { port: 3000, proxy: { /api: { target: http://localhost:8080, changeOrigin: true } } } })区分vue-cli和Vite的办法是看package.json里的devDependencies有没有vue/cli-service有就是webpack架构用vue.config.js有vite则用vite.config.js。很多校友录源码的前端是老一辈vue-cli脚手架但也有新版本换成Vite配置错位置会白耗一下午。如果需要代理多个接口前缀比如/api和/file可以并列写多个入口但每个都指向同一个target。不想写那么多的话也可以把后端接口统一加/api前缀最省事。4.3 启动页面与登录调通npm run serve、浏览器访问与Network面板依赖装好、代理配好后启动前端。npm run serve启动日志会出现App running at: Local: http://localhost:3000/。打开浏览器访问这个地址用admin/123456登录。如果页面一直转圈按F12打开开发者工具切到Network面板刷新一下登录请求。点击那个auth/login请求看它在“Preview”标签里返回什么。如果返回{code:500,msg:Request method GET not supported}说明请求方法用错了前端axios没有按post发出。如果返回401 Unauthorized说明用户名密码不对或请求头缺了token。还有一种经典情况前端登录成功但个人信息一直加载不出来。这时看Network里有没有一条校友列表请求返回403多半是token没被放进请求头。检查前端封装的axios拦截器里有没有这样一段逻辑从localStorage拿token并设置到Authorization头。如果没有就补上。// request.js 拦截器 axios.interceptors.request.use(config { const token localStorage.getItem(token) if (token) { config.headers.Authorization Bearer token } return config })这段代码在几乎所有校友录系统里都有只是写法不同。加完重启前端再试试查看校友列表、添加一条记录看数据能不能写进MySQL。能跑通说明前端到后端再到数据库这条链路已经完全打通。到这一步“能登录”这个最小闭环就成立了。如果登录后页面跳转正常但刷新又回到登录页大概率是localStorage没被保存或者路由守卫判断token的逻辑不对。路由守卫通常在src/router/index.js里检查是不是用localStorage.getItem(token)来判断而不是用响应式对象的某个属性后者刷新后必然丢失。另外很多毕设前端用Element UI登录表单里会有校验规则如果字段名和后端不一致会报“用户名不能为空”但实际输入了。这种情况优先看rules里的prop和v-model绑定的字段名是否一致。这个小问题能让新手白白怀疑半小时后端接口。5. 避坑/常见问题/排查让校友录源码稳定运行的5条血泪记录5.1 8080端口被占用导致后端启动失败找到进程与换端口现象mvn spring-boot:run启动到一半日志里出现Port 8080 was already in use或APPLICATION FAILED TO START。原因本机某个进程已经占了8080可能是另一个Java进程、Tomcat或者调试工具。解决先找占用者再决定杀还是换。# Windows netstat -ano | findstr :8080 taskkill /PID pid /F # Linux/macOS lsof -i :8080 kill -9 pid如果不想杀进程也可以在application.yml里把server.port改成8081同时记得把前端代理的target改成http://localhost:8081。毕业设计演示时经常需要同时开多个项目端口冲突是第一事故点先排练一遍能省很多事。5.2 MySQL 8的Public Key Retrieval报错和时区报错url参数补齐现象后端启动时数据源初始化报Public Key Retrieval is not allowed for this user或者The server time zone value Öйú±ê׼ʱ¼ä is unrecognized。原因MySQL 8默认的caching_sha2_password认证插件要求客户端在首次连接时获取服务器公钥而serverTimezone没设置时驱动会去读系统时区中文名导致乱码报错。解决在application.yml的url里补两个参数。url: jdbc:mysql://localhost:3306/alumni_db?useUnicodetruecharacterEncodingutf8useSSLfalseserverTimezoneAsia/ShanghaiallowPublicKeyRetrievaltrueallowPublicKeyRetrievaltrue专门解决公钥获取问题。如果用的是MySQL5.7则不需要这个参数。另外可以在数据库侧设置全局时区。SET GLOBAL time_zone 08:00;改完后重启MySQL再重启后端。如果还报Unknown database alumni_db检查是不是建库脚本没执行成功回到第3章重新确认。5.3 Maven依赖下载卡死或报Could not transfer artifact换镜像与清理lastUpdated现象mvn clean install停在Downloading: ...很长时间最后报Could not transfer artifact org.springframework.boot:spring-boot-starter-parent:...。原因默认的Maven中央仓库在部分网络环境下不稳定下载中断后留下.lastUpdated标记文件导致后续即使网络恢复也会直接跳过下载。解决在~/.m2/settings.xml中配置一个公共镜像并清掉本地仓库中损坏的缓存文件。mirrors mirror idaliyun/id mirrorOfcentral/mirrorOf urlhttps://maven.aliyun.com/repository/public/url /mirror /mirrors清缓存最简单的方法是定位到报错的那个依赖把~/.m2/repository下对应目录里的.lastUpdated删掉再重新运行mvn -U强制更新。-U参数会强制检查远程仓库是否有新版本避免本地缓存误导。如果全盘清空本地仓库下次要全部重新下载不建议。5.4 前端登录接口跨域报错或请求没到后端验证代理路径与axios baseURL现象浏览器Network里登录接口直接显示Failed to fetch或后端日志里完全没有收到请求有的是提示CORS policy: No Access-Control-Allow-Origin。原因前端请求路径没走代理或者代理配置只对/api生效但实际接口路径是/auth/login没带/api前缀。也可能axios设置了完整的baseURL比如http://localhost:8080导致代理被绕过。解决先看Network里请求的完整URL。如果显示的是http://localhost:3000/auth/login说明代理没匹配到因为代理规则写的是/api。两个办法要么把请求路径改成以/api开头要么放宽代理匹配规则。proxy: { /api: { target: http://localhost:8080, changeOrigin: true }, /auth: { target: http://localhost:8080, changeOrigin: true } }如果后端真开了跨域限制也可以在Spring Boot侧加一个CORS配置类但毕设里最推荐只用开发代理。因为代理一旦配好浏览器看到的请求是同源的根本不存在跨域。若是Vite项目还要注意.env.development里VITE_API_BASE应设为/api否则环境变量里的完整地址会绕过代理直连后端导致CORS又回来。5.5 打包后页面空白或刷新404前端路由history模式需要后端配合现象本地npm run serve一切正常但执行npm run build后把dist目录放到Nginx或Tomcat下访问首页白屏刷新某个路径直接404。原因Vue Router默认用hash模式路径里有#刷新不会404。但如果源码里改成了history模式刷新/alumni/detail/1时服务器找不到这个文件路径就会返回404如果部署到子路径还会白屏因为静态资源引用路径没带子路径前缀。解决先看src/router/index.js里mode是hash还是history。毕设演示用hash最省事不用改服务器。如果坚持用history就必须在nginx的location块里配置try_files。location / { root /usr/share/nginx/html/alumni; index index.html; try_files $uri $uri/ /index.html; }try_files的作用是当URL路径确实不存在时把请求回退到index.html让前端路由接管。如果用的是Tomcat则需要在web.xml里配置ErrorPage指向index.html顺手再确认publicPath是否为./或子路径。打包后的dist/index.html里引用JS和CSS的路径要是相对路径不然部署到二级目录又会白屏。这条是所有前后端分离项目上线的通用坑校友录系统也不例外。6. 进阶验证与调试技巧从“能跑”到“敢答辩”6.1 三个真实业务动作验证系统可靠性登录跑通只是起点。我会在答辩前用三个动作做回归验证。第一在页面上新增一位校友填写姓名、班级、电话保存后刷新页面确认数据还在。这一步验证MySQL写入与查询。第二修改当前用户密码退出后用新密码重新登录确认修改接口生效。第三步在班级列表页删除一个班级如果校友信息里还引用着这个班级看系统有没有提示“删除失败”而不是直接崩溃。这三个动作覆盖了前后端、数据库关系和异常处理比看一遍代码更能暴露隐藏问题。6.2 给校友录加一个ECharts统计图表从看懂接口到扩展接口如果还想做点亮点不妨把“班级人数统计”做成图表。先在后端写一个统计接口返回班级和人数列表前端用axios调这个接口再引入ECharts渲染。这个过程本质上是在复刻系统的核心开发流程建表、写SQL、写Mapper、暴露Controller、前端调用。完成以后你对这套源码的理解深度会超过大多数照着改参数的同学。最后说一个我自己的教训。刚拿到这类毕设源码的时候我总喜欢先改页面标题和颜色觉得换个主题就是自己的作品。后来发现真正难的不是改界面而是把启动过程中的每个日志都看明白。养成的习惯是每启动一个环节就完整截图一段启动日志端口、版本、报错行号都对一遍。这样做之后五分钟内能定位的故障越来越多。希望帮到你。本文还有配套的精品资源点击获取