先泼一盆冷水十个程序员里八个第一次跑SpringBoot项目报错不是代码问题而是Maven没配置好。我见过太多人在群里发为什么我的SpringBoot启动失败截图里清一色是Maven依赖报错、jar包标红、本地仓库乱飞。所以这篇文章不讲高大上理论就讲一件事用最短的时间把SpringBoot和Maven这对组合装好、配好、跑通顺便把路上必踩的坑提前填平。这篇内容适合完全没接触过Maven的小白也适合那种项目能跑但不知道Maven在干嘛的糊涂人。我会从两者的关系讲起再到下载安装、IDEA配置、创建项目、写第一个接口最后梳理最常见的报错场景。预计从头到尾一个小时内能跑通。1. 凭什么要先搞懂Maven再谈SpringBoot1.1 Maven到底是干嘛的用生活化的方式理解Maven本质上是个项目管家它管三件事依赖管理、构建流程、项目信息。举个装修的例子你家要装修需要水管、电线、瓷砖、水泥这些东西不可能自己开车去建材市场挨家买更不可能买回来堆在客厅自己数。Maven就相当于一个建材市场加一个仓库管理员——你只需要在图纸上写我要3吨水泥、200块瓷砖它就能把材料搬到仓库里再按施工进度送到工人手上。对应到Java开发你在pom.xml里写一行依赖坐标Maven就从中央仓库类比建材市场下载对应的jar包放到本地仓库类比你家仓库再把你项目里用到的所有jar包路径编进classpath。整个过程不需要你手动下载任何jar包也不用担心版本冲突。1.2 SpringBoot的出现解决了什么问题没有SpringBoot的年代做Java Web开发相当痛苦。你需要手动配置web.xml、Spring配置文件、数据源连接、事务管理还要引入一堆依赖并且保证版本兼容。说难听点项目还没开始写业务代码光配置就花了一两天。SpringBoot的核心思路是约定优于配置把绝大多数配置兜底成默认值你只需要写业务逻辑。再加上内嵌Tomcat一个java -jar就能启动Web服务部署成本大幅下降。这里要注意SpringBoot是建立在Maven之上的。SpringBoot帮你约定好了依赖版本但它仍然需要Maven把这些依赖下载下来并且管理好整个项目的构建。所以你会发现每个SpringBoot项目的根目录都必然有一个pom.xml——这就是Maven的配置文件是整个项目的材料清单。1.3 为什么很多入门者项目跑不起来90%怪Maven我见过一个很有意思的规律新手在SpringBoot上遇到的第一个拦路虎不是SpringBoot本身而是Maven的环境问题和依赖下载问题。原因有三条第一JDK版本和Maven版本不匹配。第二IDEA自带的Maven路径与你自己安装的Maven路径混淆导致配置失效。第三国内网络访问Maven中央仓库太慢依赖下载几个小时都下不完。这三条在后面的章节里我会逐个给出处理方案而且都是被验证过很多次的方案。2. 环境准备JDK、Maven下载安装与配置2.1 先选JDKSpringBoot版本和JDK版本必须对应现在网上教程鱼龙混杂有人教你用JDK 8配SpringBoot 3.x启动必炸。版本兼容是个硬规矩我按自己验证过的组合整理了一张对应表SpringBoot版本最低JDK版本你该选哪个JDKSpringBoot 2.xJDK 8JDK 8或JDK 11最稳SpringBoot 3.0 - 3.2JDK 17JDK 17SpringBoot 3.3JDK 17JDK 21也可以但JDK 17更省心如果你只是学习快速上手我建议直接选SpringBoot 2.7.x JDK 8资料多、坑少、网上报错方案齐全。如果你想要新特性再考虑SpringBoot 3.x JDK 17。千万别学一些教程拿SpringBoot 3去配JDK 8那不是挑战自我是自找麻烦。JDK安装没什么技巧下载官方包或OpenJDK都行配好JAVA_HOME环境变量在命令行输入java -version能打印版本就说明OK了。这里要提醒一句如果你之前装过好几个JDK版本打开命令行前确认当前生效的是不是你要的那个。很多人配了JAVA_HOME但没刷新终端结果用的还是旧版本。2.2 Maven下载安装与配置核心是阿里云镜像Maven的下载地址是Maven官网选apache-maven-3.9.x的bin.tar.gzLinux/Mac或bin.zipWindows版本别下source包。下载后直接解压到一个路径简单的目录比如Windows下放D:\mavenMac/Linux下放/usr/local/maven。然后配置环境变量Windows新增系统变量MAVEN_HOME指向解压目录把%MAVEN_HOME%\bin加到Path中。Mac/Linux在~/.zshrc或~/.bash_profile里加export MAVEN_HOME/usr/local/maven和export PATH$MAVEN_HOME/bin:$PATH。配好后命令行执行mvn -v能显示Maven版本和Java版本就说明装好了。但到这一步只是万里长征第一步——如果你直接跑mvn clean install接下来会体验什么叫等到花儿都谢了。默认中央仓库在国外不挂加速的情况下下载速度极其感人。所以安装完Maven的第一件事就是改配置文件settings.xml。这个文件在Maven解压目录的conf文件夹下。在里面加阿里云镜像配置settings xmlnshttp://maven.apache.org/SETTINGS/1.0.0 xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd localRepositoryD:/maven-repo/localRepository mirrors mirror idaliyunmaven/id mirrorOfcentral/mirrorOf name阿里云公共仓库/name urlhttps://maven.aliyun.com/repository/public/url /mirror /mirrors /settings这里的localRepository是本地仓库路径也就是jar包在你电脑上的存放位置。默认在用户目录的.m2/repository下我习惯自定义到项目盘免得C盘爆炸。完成之后jar包下载速度基本是秒开。2.3 本地仓库是什么装好的jar包都堆哪本地仓库这个概念一定要理解。所有用Maven构建的项目依赖的jar包都不是放在项目目录里的而是统一存放在一个本地仓库地址。第一次配置好的时候这个文件夹是空的随着你不断构建项目依赖会被下载到这里。多个项目如果用了同一个依赖直接复用本地仓库缓存所以本地仓库越来越大是正常现象不需要慌。有的新手会把本地仓库路径设置的特别奇怪比如放到桌面或者项目代码目录里这会导致个项目一个仓库磁盘爆炸且构建缓慢。记住本地仓库是全局的跟具体项目无关放在一个固定目录即可。3. IDEA中配置Maven别用自带默认值3.1 为什么IDEA自带Maven我还是要你改成自己的IDEA确实内置了一个Maven但它内置的版本可能跟你的项目要求不匹配而且默认的settings.xml还是中央仓库配置下载依然慢。更关键的是IDEA默认的Maven配置只对当前项目生效你新开项目又要重新配一遍很烦。我自己的习惯是统一用自己装好的MavenIDEA里一次性配好后续所有项目都继承。打开IDEA进入Settings或Preferences搜索Maven你会看到三栏配置Maven home path选择你自己安装的Maven目录。User settings file选择刚才修改过的settings.xml点击旁边的Override可以强制覆盖。Local repository会自动识别成settings.xml里配置的路径如果不一致点击Override手动指过去。这三栏只要对应正确IDEA右下角的Maven面板就会显示你配置的环境。写到这里顺便提一个很多人忽略的点IDEA在导入项目时如果右下角弹出Maven projects need to be imported别点Disable记得点Enable Auto-Import不然改动pom.xml后依赖不会自动更新。3.2 IDEA新建SpringBoot项目的两种方式第一种在https://start.spring.io网站上在线生成项目。页面里选Maven、Java版本、SpringBoot版本再选需要的依赖Web、MyBatis、Lombok之类的点击Generate下载一个zip包解压后用IDEA打开即可。第二种IDEA内置的Spring Initializr。新建项目时选择Spring Initializr填写Group和Artifact再选SpringBoot版本勾选依赖IDEA会直接拉取模板生成项目。两种方式本质上都是生成一个标准的SpringBoot项目结构。这里我推荐初学者用第一种因为你可以看到网页上每个依赖都写了说明认知负担小一些。等熟练了IDEA内置的方式效率更高。3.3 命令行构建mvn clean install到底干了什么很多教程让你配完环境后跑一下mvn clean install但没人说这行命令具体干了什么。我来拆解一下clean删除target目录下的所有编译产物也就是清空上次构建的结果。install执行完整的构建流程——编译Java源码、执行单元测试、打包jar或war、并把产物安装到本地仓库中。所以mvn clean install的意思是从头来一遍完整构建最后把可执行的jar包放到本地仓库供其他项目引用。在SpringBoot项目里经常用mvn clean package它和install的区别就是package只打包到target目录不装进本地仓库。你只需要知道日常用mvn clean install最稳。如果你不想在命令行操作IDEA的Maven面板里双击clean和install效果一样。但刚入门我还是建议命令行执行一次体会一下Maven的构建输出看到BUILD SUCCESS你就知道整个链路没问题了。4. 创建并跑通第一个SpringBoot项目4.1 项目目录结构先看懂这几个文件打开生成的SpringBoot项目后你会看到这样一个目录结构my-demo/ ├── pom.xml ├── src/ │ ├── main/ │ │ ├── java/com/example/mydemo/ │ │ │ ├── MyDemoApplication.java │ │ │ └── controller/HelloController.java │ │ └── resources/ │ │ └── application.properties │ └── test/java/com/example/mydemo/对初学者来说先关注四件事pom.xmlMaven的配置文件SpringBoot的依赖清单和版本信息全在这里。MyDemoApplication.java项目启动类里面是main方法SpringBoot应用从这里启动。application.properties项目配置文件端口号、数据库连接、日志级别都写在这里。test目录单元测试代码写业务代码时可以顺手写测试。这四个文件看懂了你的项目骨架就明白了。别急着把目录结构全部吃透先跑起来后面用得多了自然会熟悉。4.2 pom.xml核心解析为什么SpringBoot这么省心打开pom.xml你会发现整个文件的核心就三块内容。第一块是parent它继承了spring-boot-starter-parent这样做的好处是SpringBoot帮你锁定了所有常用依赖的版本号你不需要为每个依赖指定version。第二块是dependency也就是你需要的组件。最简单的Web项目只需要一个spring-boot-starter-web它就自动打包了Spring MVC、内置Tomcat、Jackson等一整套Web开发环境。第三块是插件主要是spring-boot-maven-plugin它负责在打包时把项目打成可执行的fat jar。这里插一句很多新人看到pom.xml里的依赖很多都懵了但其实大部分都不是你手动加的而是starter自动替你引入的。这就是SpringBoot的魔法所在。如果你想确认项目里到底依赖了哪些jar包在IDEA右侧的Maven面板里展开Dependencies就能看到完整依赖树。4.3 写一个Controller并启动验证整条链路创建一个HelloController.java代码如下package com.example.mydemo.controller; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RestController; RestController public class HelloController { GetMapping(/hello) public String hello() { return Hello, SpringBoot!; } }然后点击启动类MyDemoApplication里的main方法看到控制台打印出Tomcat started on port(s): 8080就说明项目启动成功了。打开浏览器访问http://localhost:8080/hello如果页面显示Hello, SpringBoot!恭喜你你第一个SpringBoot项目正式跑通了。启动过程如果报错九成都是端口被占用或者依赖没下载完。端口占用的话在application.properties里加一行server.port8081换个端口即可。依赖没下载完的话看IDEA右下角是不是还在转圈等一会或者重新点击一下Maven刷新按钮。5. 依赖管理不迷路SpringBoot版本选择与避坑5.1 版本号都在哪管原来SpringBoot早就帮你锁好了初学SpringBoot的人经常遇到的问题为什么我在pom.xml里写依赖可以不写version答案是spring-boot-starter-parent已经通过dependencyManagement把一大批常用依赖的版本统一管理起来了。你引入依赖时只要写groupId和artifactIdMaven会自动取parent里锁定的版本。这个设计简直太舒服了——团队里所有人都用同一套版本谁也不会因为擅自升级依赖搞出线上事故。但是反过来也有一个坑当你想用某个不在parent管理列表里的依赖时就必须手动指定version。比如我想用某个小众的工具库在网上找依赖配置看到别人没写版本号就抄过来结果Maven报错dependencies.dependency.version is missing。这个报错的意思就是这个依赖不在SpringBoot的统一版本管理里你必须自己加上版本号。5.2 版本冲突怎么办一个最实用的观察方法版本冲突是Maven使用者的经典噩梦。最典型的场景是你引入了A库A库内部又依赖了B库的1.0版本另外你又直接引入了B库2.0。Maven默认采用最近优先策略谁在依赖树里离根项目近就用谁的版本。但是这种自动策略并不能保证运行时稳定有时候编译能过运行起来就抛异常。我的建议是遇到版本冲突先用mvn dependency:tree命令查看完整依赖树。命令行输出会清楚显示某个依赖是从哪条路径引入的版本号是多少。确定冲突后在pom.xml里用exclusion排除掉不需要的那份依赖dependency groupIdcom.example/groupId artifactIdsome-library/artifactId version2.0/version exclusions exclusion groupIdcom.example/groupId artifactIdold-library/artifactId /exclusion /exclusions /dependency这个操作看起来很硬核但实际应用中并不算多。大多数时候你只是引入Web、MyBatis、MySQL这些基础依赖版本冲突的概率很低。等做复杂项目再深入也不迟快速上手阶段只需要知道有这回事。5.3 最常用的依赖组合直接抄作业下面是我在快速开发和毕设项目里最常用的一套依赖组合新手可以参考!-- Web开发环境 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency !-- MyBatis框架 -- dependency groupIdorg.mybatis.spring.boot/groupId artifactIdmybatis-spring-boot-starter/artifactId version2.3.0/version /dependency !-- MySQL驱动 -- dependency groupIdcom.mysql/groupId artifactIdmysql-connector-j/artifactId scoperuntime/scope /dependency !-- Lombok减少样板代码 -- dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId optionaltrue/optional /dependency值得注意的是mybatis-spring-boot-starter不在SpringBoot的parent版本管理体系里所以它需要手动指定版本这个在MyBatis官方文档里有说明。Lombok的作用是自动生成getter/setter、构造方法等代码属于编译期工具所以optional设为true避免打进最终包里。profile中加不加这些依赖取决于你的项目具体需求但Web和MySQL是绝大多数后端项目的起点。6. 遇到报错别慌高频问题排查与操作经验6.1 依赖下载慢、下载失败实战处理方案这是个高频中的高频问题。如果你按我前文配置了阿里云镜像大部分慢的问题都解决了。但还有几种特殊情况第一种公司内部需要私服仓库。比如你们公司把公共依赖放在内网Nexus私服上这时光配阿里云镜像没用。你需要把私服地址也配到mirrors或repositories中。多个仓库共存时Maven会依次尝试直到找到对应依赖。第二种某个依赖在阿里云镜像里也没有只有中央仓库才有。这种情况可以把镜像改成mirrorOf为*但实际体验不好我更建议保持central剩下的依赖走特定仓库。第三种本地仓库缓存了损坏的jar包。症状是每次构建停在某个jar包下载不报错又不出结果。排查方法是进入本地仓库对应目录删掉*.lastUpdated结尾的文件重新构建。这个文件代表之前的下载失败记录Maven看到它就会跳过重新下载。删掉后重新执行构建一般就能继续下载。6.2 IDEA里依赖报红、代码标红怎么破代码里import语句报红、Maven面板里某个依赖也标红大概率不是代码问题而是Maven索引还没更新。我习惯用的三板斧第一板斧点击Maven面板里的刷新按钮两个循环箭头图标让IDEA重新解析pom.xml。第二板斧执行mvn clean install看命令行有没有具体报错。第三板斧如果还不行执行mvn -U clean install强制检查远程仓库最新版本用于解决缓存导致的依赖过期。如果这三个方法都无效再考虑删除target目录和本地仓库里的相关缓存。说实话我踩过的最坑的一次是本地仓库里旧版本的jar包被IDEA优先加载刷新也没用最后删掉了本地仓库里对应目录才解决。这个过程很简单找到本地仓库路径下的org/example/xxx目录直接删除然后重新构建。6.3 SpringBoot版本太高导致的坑以及如何降级热搜词里有个很典型的问题springboot版本太高。这个情况通常是指你新建项目时选了最新版SpringBoot结果代码里用到了一些旧的API或者构建插件不兼容。比如SpringBoot 3.x把javax.*包换成了jakarta.*包很多旧教程里的import javax.servlet.*在3.x下直接编译失败。解决办法有两种第一种是降版本把pom.xml里的SpringBoot版本换成2.7.x同时JDK切回8或11。这种适合你只需要完成学习任务或毕业设计没必要追新。第二种是适应新版本把所有javax改成jakarta并查阅对应版本的官方文档。这种适合你在生产环境需要新特性。我个人的经验是教学项目和毕设选2.7.x生产选官方LTS版本不要盲目追求最新。稳定压倒一切这个话在Java世界里永远不会过时。6.4 前端打包进SpringBoot的一个小技巧热搜词里还有vue打包放进springboot中这确实是很多全栈项目会遇到的问题。原理非常简单Vue项目打包后会生成静态资源HTML、JS、CSS你只要把这些文件复制到SpringBoot项目的src/main/resources/static目录下启动SpringBoot后浏览器访问http://localhost:8080/就能直接看到前端页面。如果Vue项目里配置了路由比如history模式刷新页面会出现404。这时需要写一个转发规则把非接口请求都转发到首页。这个对快速上手来说是进阶内容建议先跑通接口再研究前后端整合。7. 一点个人实操体会写了这么多最后再分享几个平时开发的小习惯。第一settings.xml是Maven的全局配置配好一次受益终身我一般在装完Maven后第一时间就配镜像再顺手把本地仓库路径改掉避免后续每个项目都折腾。第二遇到看不懂的报错第一反应不要是百度先执行mvn clean install看完整日志多数问题在日志里就有答案百度出来的方案反而可能是别人项目里的特殊情况。第三SpringBoot的版本号跟着官方节奏走2.7及3.x系列都有各自的生态正常运行的项目别手贱升级上线前升级依赖属于高风险操作。SpringBoot和Maven这对组合本身没什么高深莫测的Maven管的是材料怎么来SpringBoot管的是项目怎么跑。把这两个基础打牢后面学MyBatis、Redis、消息队列都会顺很多。这篇文章里的每一步我都实际跑过照着操作基本一遍过。如果哪一步卡住了仔细对照检查版本和环境变量多半是细节没对齐。