去年一年我帮好几个同事处理过“IDEA里创建SpringBoot项目”的各种问题包括刚转Java的、从Eclipse迁移过来的甚至还有几个经验不少但第一次用Spring Initializr的老手。我发现一个很有意思的现象真正卡住人的往往不是SpringBoot本身而是创建项目这个入口环节——版本选不对、依赖不知道勾哪个、项目建完启动就报错。这篇我直接把2023年这套流程掰开揉碎写清楚从IDEA配置讲到第一个接口跑起来每一步都解释为什么这么做。不废话直接开始。1. 动手前的准备IDEA版本与JDK环境1.1 IDEA旗舰版和社区版的区别到底用哪个IntelliJ IDEA分Ultimate旗舰版和Community社区版两个版本。旗舰版是收费的社区版完全免费。很多新人会纠结这个问题我直接说结论如果你只是学SpringBoot、写点个人项目社区版就够了。虽然早期社区版对SpringBoot的支持很有限但2021以后JetBrains把很多功能下放给了社区版现在社区版已经内置了Spring Initializr能直接创建SpringBoot项目这对个人学习和轻量开发完全够用。不过有几点你心里要有数。社区版没有Spring相关的高级辅助功能比如Autowired的依赖注入图表、Spring Bean的可视化关联、Spring Boot运行时的Actuator面板、JPA Designer可视化工具等。这些在开发大型企业级项目时确实能提升效率但在学习阶段、写毕设、做个人项目的场景下缺失这些功能几乎没有影响。我自己早期写SpringBoot项目就是在社区版上完成的。另外旗舰版对于前端资源文件、JavaScript、TypeScript的智能提示也更完善一些如果你同时搞前后端分离开发旗舰版的体验会更顺。但如果你只是后端为主社区版加上一个VS Code写前端就足够了。如果你还在用2019、2020年甚至更老的IDEA版本我强烈建议你升级。太老的版本内置的Spring Initializr模板很旧生成的SpringBoot版本是2.1、2.2这类老版本甚至有的版本根本不支持Spring Initializr向导只能去网页端手动生成再导进来。而2023版的IDEA内置模板已经跟上了SpringBoot 3.x的节奏还会读你本地Maven仓库里的版本信息体验完全不一样。我见过太多人卡在“学校里用2018版IDEA到公司打开项目一堆依赖报错”的窘境真没必要用老版本为难自己。1.2 JDK装错了项目一启动就崩创建SpringBoot项目之前最好先确认JDK真的配好了。这里有一个2023年尤其容易踩的坑SpringBoot 3.x要求JDK 17及以上而SpringBoot 2.x用JDK 8或11都行。所以不是随便装个JDK就能跑通所有项目。我的建议是学习新项目直接用JDK 17这是目前性价比最均衡的版本。怎么检查你电脑上的JDK打开命令行工具输入java -version如果显示的是openjdk version 17.x.x或者java version 1.8.0_xxx你心里就有数了。如果提示“不是内部或外部命令”那说明你的JAVA_HOME环境变量没配好IDEA里即使配置了JDK路径命令行也找不到。这里有个小技巧IDEA其实不依赖系统的JAVA_HOME你只要在Project Structure里指定了JDK路径IDEA就能正常工作。但Maven在命令行里执行时需要JAVA_HOME所以建议还是把环境变量配好省得后面打包部署时出幺蛾子。配JDK环境变量的时候注意JAVA_HOME要指向JDK的安装根目录而不是bin目录。Path里加%JAVA_HOME%\binWindows系统或$JAVA_HOME/binmacOS/Linux系统。配置完打开新命令行窗口验证一下。如果IDEA里已经安装了多个JDK版本可以在File - Project Structure - SDKs里添加不同版本然后切换项目用的SDK。这一点对老项目和新项目来回切换很关键。2. 创建项目一步一步走完是关键2.1 新项目向导里的那些配置项到底什么意思打开IDEA点击File - New - Project弹出的窗口里选择Spring Initializr。2023版IDEA在这里会分成两栏左侧是项目模板类型右侧是参数配置。这里每一个选项都有讲究。Server URL默认是https://start.spring.io这是Spring官方的初始化服务地址它会根据你选的参数生成一个项目压缩包。国内网络偶尔会连这个地址超时如果碰到了可以换成阿里云的镜像地址https://start.aliyun.com。但注意阿里云镜像里某些新版本的SpringBoot可能还没同步版本列表会落后一点所以优先用官方地址超时再切换。Name项目名称就是你的项目名会自动作为Artifact的一部分。注意项目名尽量用英文小写短横线分隔比如my-springboot-app不要用中文或大写字母开头。否则后面Maven构建时会有奇怪的路径问题。Language默认Java就行。Kotlin和Groovy版本适合有其他需求的开发者正常学SpringBoot选Java。TypeMaven和Gradle二选一。Maven是主流选择绝大多数教程、公司项目都用它依赖管理生态成熟。Gradle构建更快、配置更灵活但学习曲线稍陡初学者别折腾选Maven。Group、Artifact、Package name这三个是Maven坐标的核心。Group通常写公司域名倒序比如com.exampleArtifact通常和项目名一致Package name默认就是com.example.myproject这个就是你的包根路径后面所有Java类都放在这个包下面。这里建议自己想清楚再填建好项目再改包名很麻烦IDEA的Refactor虽然能改但涉及路径引用的地方多了会出问题。把这些搞清楚之后JDK栏选你安装的JDK版本。如果这里没有显示你装的JDK点Add JDK手动添加路径。Java版本下拉框一般会自动匹配JDK版本。2.2 依赖到底勾哪几个新手推荐组合与含义到了Dependencies这一步很多人会懵一堆依赖名看得眼花缭乱。其实完全不用慌初期只需要勾这几个依赖作用我的建议Spring Web提供Tomcat内嵌服务器、Spring MVC、REST接口支持是所有Web项目的核心必选Spring Boot DevTools热部署工具改了代码自动重启强烈建议勾上Lombok通过注解省略getter/setter/构造器代码让实体类干净很多强烈建议勾上Spring Configuration Processor写配置文件时有自动提示和校验建议勾上Thymeleaf服务端渲染模板引擎做纯后端API的话不勾做页面渲染再勾Spring Data JPA / MyBatis数据持久层框架新手阶段可以先不选后面用到再手动加依赖这其实是很多人不知道的细节Spring Initializr只是生成模版项目之后你可以随时在pom.xml里手动加依赖。所以创建项目时少勾两个依赖完全不是问题勾错了也不影响什么。但Spring Web这个千万别漏了漏了你就只能在控制台打Hello World了浏览器根本访问不到。2.3 项目生成后的目录结构每层是干嘛的点击Finish后IDEA会拉取项目依赖并构建目录。第一次构建可能需要几分钟进度条一直在转这是Maven在从中央仓库下载依赖。如果你的网络状态不好这一步可能报错解决方案我在第4节专门说。构建完成后整个项目的结构长这样my-springboot-app/ ├── src/ │ ├── main/ │ │ ├── java/ │ │ │ └── com/example/myproject/ │ │ │ ├── MySpringbootAppApplication.java │ │ │ └── ... │ │ └── resources/ │ │ ├── application.properties或application.yml │ │ ├── static/ │ │ ├── templates/ │ │ └── ... │ └── test/ │ └── java/ │ └── ... ├── .mvn/ ├── mvnw / mvnw.cmd ├── pom.xml └── .gitignoreMySpringbootAppApplication.java是启动类里面有main方法运行它就等于启动了整个SpringBoot应用。application.properties是配置文件不过我个人强烈建议你把它改成application.ymlYAML格式的层级结构更清晰写复杂配置时可读性高得多。pom.xml是Maven的配置文件所有依赖都写在这里。到这里项目创建完毕。下一步就是运行起来。3. 从启动类到第一个接口把项目跑起来3.1 SpringBootApplication背后的组合魔法新建的启动类上有SpringBootApplication注解就这一行注解背后做了一大堆事情。它其实是三个注解的合成体SpringBootConfiguration标记这是Spring Boot的配置类继承自Configuration。告诉Spring容器“这个类里有Bean定义”。EnableAutoConfiguration这是SpringBoot的核心魔法。它根据你pom.xml里引入的依赖自动帮你配好大量默认的Bean。比如你引入了spring-boot-starter-web它就自动配置好DispatcherServlet、Tomcat内嵌服务器、Jackson消息转换器等等。省去了传统Spring项目中一大堆XML配置或Configuration类。ComponentScan默认扫描启动类当前包及其子包下的所有Component、Service、Controller、Repository等注解类把它们注册进Spring容器。如果你启动类所在的包名是com.example.myproject那么你新加的Controller放在com.example.myproject.controller下面就能被扫描到。如果你把Controller放到com.example.other包下那就扫描不到访问接口时直接404。这个坑我见过太多次了特别是从别的项目里复制代码过来时包名对不上就出问题。3.2 写一个Controller验证项目是真的通了创建项目后第一件事不是写业务代码而是先写一个测试接口验证项目能正常启动并响应请求。打开启动类右键点击main方法选择Run。IDEA底部控制台开始刷日志等几秒你看到类似这样的输出Tomcat started on port(s): 8080 (http) with context path Started MySpringbootAppApplication in 2.3 seconds (process running)看到这行项目启动成功了。这行日志的意思是你的内嵌Tomcat监听在8080端口Spring容器初始化完成用了2.3秒。此时你打开浏览器输入http://localhost:8080大概率看到的是一个默认的错误页面因为没有配置任何接口这是正常的。现在我们来写第一个接口。在启动类同级的包下新建一个controller包然后在里面创建HelloController.javapackage com.example.myproject.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, Spring Boot!; } }RestController表示这是一个处理HTTP请求的控制器并且返回值直接写入响应体不做视图渲染。GetMapping(/hello)表示当浏览器访问/hello路径的GET请求时执行这个方法。保存文件后如果你的IDEA装了DevTools项目会自动重启。没装的话你手动重启一下。然后在浏览器访问http://localhost:8080/hello看到Hello, Spring Boot!就说明一切正常了。3.3 application.yml配置端口、上下文路径与日志application.properties或application.yml是SpringBoot的配置文件里面可以修改端口、数据库地址、日志级别等等。我每次新建项目都会先把几个基础配置写上省得后续开发时来回查server: port: 8080 servlet: context-path: /api spring: application: name: my-springboot-app logging: level: root: info com.example.myproject: debugserver.port把端口改成其他值比如8081可以避免本机端口冲突。context-path设置一个统一前缀这样接口地址就变成了http://localhost:8080/api/hello。logging.level把指定路径下日志级别设为debug开发阶段能看到更详细的SQL和调试信息排查问题方便很多。这里提醒一句application.yml对缩进非常敏感YAML格式靠缩进区分层级不能用Tab键缩进要用空格。IDEA默认帮你处理好了但是如果你从其他地方复制配置过来容易混入Tab导致启动时报java.util.Scanner异常或解析错误。如果遇到启动报配置文件相关的错误先检查YAML缩进。4. 创建项目时最常见的几个坑一次说透4.1 SpringBoot版本太高导致Jar包冲突和编译失败2023年的SpringBoot已经出到了3.1、3.2版本很多人在Initializr里直接选了最新版结果项目一创建Maven同步依赖时报错或者IDE里依赖列表一堆红波浪线。这不是IDEA的问题大多数情况是版本和JDK不匹配。SpringBoot 3.x是2022年11月发布的大版本它基于Jakarta EE 9包名从javax.*改成了jakarta.*并且强制要求JDK 17及以上。如果你本机装的是JDK 8或11拿一个SpringBoot 3.x项目去跑启动时会直接报UnsupportedClassVersionError或者一堆ClassNotFoundException。怎么处理如果你用的是JDK 8或11创建项目时在Spring Initializr界面把SpringBoot版本切换到2.7.x系列这是2.x的最终维护版本稳定且兼容JDK 8/11。如果你确实想用SpringBoot 3.x体验最新特性那先把JDK升到17再说。实际操作中我建议你不要执着于最新版稳定压倒一切。3.x发布初期很多第三方starter还没适配jakarta.*命名空间你连MyBatis都得用专门的mybatis-spring-boot-starter版本才能兼容。如果不是跟着教程走且教程明确要求3.x默认用2.7.x更稳。版本改动是怎么操作的呢在IDEA右侧Maven面板展开Lifecycle执行clean和compile前先改pom.xml里的版本号parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version2.7.18/version relativePath/ /parent改成2.7.18后保存Maven会自动重新解析依赖。这是最直接、也最不容易出问题的方式。4.2 Maven依赖下载慢和下载失败本地仓库配置Maven首次加载SpringBoot依赖时如果长时间卡住或者直接报Cannot resolve ...的错误十有八九是网络问题。Maven默认从中央仓库下载国内访问速度很不稳定。解决办法是配置阿里云镜像仓库。打开IDEA进入Settings - Build, Execution, Deployment - Build Tools - Maven找到User settings file对应的settings.xml没有的话自己建一个把这段配置加进去mirrors mirror idaliyunmaven/id mirrorOfcentral/mirrorOf name阿里云公共仓库/name urlhttps://maven.aliyun.com/repository/public/url /mirror /mirrorsmirrorOf设为central表示所有中央仓库的请求都走阿里云镜像。配置完点Apply然后重新加载Maven项目速度提升非常明显。如果你在IDEA里改了settings.xml不生效注意Maven的Local repository路径和User settings file路径必须是同一个配置文件别在IDEA里指来指去指错了。4.3 端口被占用8080起不来怎么办SpringBoot默认端口是8080如果你本机其他程序占了8080端口比如之前启动过其他服务没关掉启动时报错会看到Web server failed to start. Port 8080 was already in use.这时候分两步排查。第一步找到是谁占用了端口。Windows在命令行输入netstat -ano | findstr 8080macOS/Linux输入lsof -i :8080找到占用进程的PID然后根据实际情况关掉它或者直接改SpringBoot端口。第二步不排查了直接改端口。在application.yml里设置server.port: 8081重启就完事。我个人建议开发阶段直接用随机端口比如server.port: 0这样每次启动都会自动分配一个空闲端口IDEA控制台日志会告诉你实际端口。但这样有个缺点访问地址飘忽不定。所以还是固定端口更实用只是要注意本机端口规划。5. 提高效率的技巧工具与扩展5.1 Lombok省掉重复代码刚才创建项目时建议勾选Lombok现在就来看看它省了什么。Java实体类通常要写一堆getter/setter/toStringLombok通过注解在编译期自动生成这些方法代码量减少一半以上。比如package com.example.myproject.entity; import lombok.Data; Data public class User { private Long id; private String name; private String email; }Data注解编译后自动生成所有字段的getter、setter、toString、equals和hashCode方法。代码里直接写user.getName()就行完全不用手写这些样板代码。除了Data常用的还有Slf4j生成日志对象log、Builder建造者模式、AllArgsConstructor全参构造器。不过注意用Lombok的时候IDEA必须安装Lombok插件新版IDEA已内置并且在Settings - Build - Compiler - Annotation Processors里勾选Enable annotation processing否则编译时Lombok注解不生效你会看到一堆“找不到符号getXxx”的错误。5.2 DevTools热部署改代码不用反复重启DevTools是SpringBoot提供的开发期热部署工具原理是监听classpath文件变化变化后自动重启应用。实测下来比手动重启快不少特别是在项目慢慢变大之后。配置完成后每次你修改Controller、Service里的代码并保存控制台就会自动触发重启整个过程大概2到3秒省去手动切窗口点重启按钮的时间。也有人会说“DevTools一直重启很烦”那是因为你频繁改配置文件。DevTools对classpath里的文件变化是重新加载对静态资源HTML、CSS、JS则只做浏览器刷新不做重启两种策略不一样。如果你只是想改前端页面就自动刷新需要在application.yml里配置spring: devtools: livereload: enabled: true我个人的配置习惯是写后端逻辑时开DevTools自动重启写前端页面时关掉重启、用浏览器插件配合livereload。实际项目中我更多是开着DevTools代码保存即生效效率提升很明显。5.3 Spring Boot Banner给你的启动界面加个定制皮肤这是个小彩蛋。每次SpringBoot启动时控制台都会打印一个ASCII艺术字体的“Spring”横幅。这个横幅其实是可以定制的。你可以到src/main/resources目录下新建一个banner.txt文件把你想显示的ASCII字符画放进去启动时它就会覆盖默认的Spring Banner。网上有专门的Spring Boot Banner生成器可以输入文字自动生成ASCII艺术字。甚至如果你想优雅地隐藏横幅在application.yml里写spring.main.banner-mode: off就能关闭。这个功能虽然不影响业务逻辑但团队项目里加上一个项目名称横幅启动时视觉上会专业很多。6. 项目扩展的下一步建议创建并跑通第一个SpringBoot项目只是起点。接下来你有几个明确的方向值得探索。第一个是整合数据库。先加一个MySQL驱动和JPA或MyBatis依赖配置好数据源写一个实体类、一个Repository或Mapper接口体验一下ORM的便捷。这里我建议新手先试Spring Data JPA因为它几乎不用写SQL就能实现基础CRUD。第二步是写一个RESTful接口把数据通过JSON格式返回给前端配合RestControllerAdvice实现统一异常处理让接口更健壮。然后再做统一响应体封装比如返回{code: 200, data: ..., message: success}这个阶段你会真正理解前后端如何通过约定格式对接。第三件事是学会单元测试。SpringBoot对测试支持很完善spring-boot-starter-test里有JUnit、Mockito等全套工具。不要觉得写测试是浪费时间等你改完代码发现接口行为变了、系统自动报错的时候就知道测试的价值了。第四件值得做的事是尝试用IDEA的Docker集成插件把项目打包成Docker镜像体验一次“一次构建、到处运行”的工作流。如果你要做前后端分离项目IDEA里创建SpringBoot项目后前端用Vue或React单独建立项目通过HTTP请求调用后端接口注意处理跨域问题在Controller上加CrossOrigin或在配置类里注册CorsFilter。这个开发模式是目前市面上最常见的全栈开发范式你现在创建的SpringBoot项目日后完全可以长成那个形态。6.1 从SpringMVC工程迁移到SpringBoot的快捷思路我之前接过一些老项目代码是用传统的SpringMVCXML配置写的。把它们改造成SpringBoot不用重写业务代码关键是处理好下面四点web.xml里配置的DispatcherServlet、ContextLoaderListener全部删除SpringBoot的自动配置会搞定这些。Spring的XML配置文件中mvc:annotation-driven/、context:component-scan这些标签换成对应的Configuration类或ComponentScan注解。applicationContext.xml里的数据源、事务管理器、MyBatis配置按SpringBoot的风格改写成application.yml数据源配置MyBatis直接引入mybatis-spring-boot-starter。JSP视图层如果还继续用需要加spring-boot-starter-tomcat并调整目录结构而如果你用的是模板引擎Thymeleaf、FreeMarker替换起来就自然很多。大部分老工程的Service和Controller代码可以原封不动搬过来真正要动的只是配置和依赖部分。改造完后你会发现项目清爽得多没有几十行XML要维护了。7. 最后的几点碎碎念整个创建SpringBoot项目的流程看起来就是点几下鼠标、写一个Controller但背后涉及了Maven坐标、依赖管理、自动配置、内嵌服务器等多个概念体系。新手阶段不要求全部理解先把流程跑通、把“项目能启动、接口能访问”这个正循环建立起来后面再逐个概念深入理解学习成本会低很多。我自己带过不少新人凡是能顺利把第一个项目跑起来的后面学注解、学依赖注入、学数据库整合进度都会快得多。有一个习惯我特别推荐每次新建项目把pom.xml文件的依赖梳理一遍搞清楚这个依赖是干什么用的是从哪个传递依赖被带进来的。用Maven面板里的Dependencies视图可以看到依赖树。这一步能把你从“复制粘贴pom”的状态中解放出来。我自己也是这么过来的依赖管理理解了Maven就基本掌握了SpringBoot项目的构建逻辑也随之清晰。最后如果你已经成功跑起来了这个示例项目把启动类、Controller、配置文件这三样内容作为你继续探索SpringBoot世界的基础。后面无论是读源码还是做项目这三块是你每一次都会遇到的核心骨架。