咱们直接聊正事。2023年了还在问怎么在IDEA里创建SpringBoot项目的人多半是刚把JDK装好、对Maven一脸懵、或者被网上各种版本的教程绕晕了。我每年都要带几个新人眼睁睁看着他们在这一步卡上一两天其实真不是什么难题。这篇东西我就按2023年当时最顺手的做法把创建SpringBoot项目的完整流程、版本选择逻辑、常见坑位一次讲透环境、步骤、配置、排错全都覆盖不管你用的是IDEA社区版还是正式版照着做就行。1. 开工前想清楚的三件事版本、JDK与构建工具很多新手犯的第一个错误不是不会点鼠标而是没想清楚版本搭配就直接开干结果项目创建出来了启动直接报错一堆然后开始怀疑人生。在点New Project之前建议先把三件事定下来JDK版本、SpringBoot版本、构建工具。1.1 先选JDK再选SpringBoot版本别让版本拖后腿SpringBoot版本和JDK版本是强绑定的。你JDK用的8却硬要创建SpringBoot 3.x的项目那连项目初始化那一步都过不去就算IDEA帮你生成了Maven一拉依赖就会报错。我在实际项目里长期用的是这个搭配逻辑JDK 8 配 Spring Boot 2.7.x这是以前最经典的组合企业里存量项目最多的就是它。如果你的运行环境是老服务器、或者依赖里有老版本中间件选这套最稳。JDK 17 配 Spring Boot 3.x这是2023年的主流方向。Spring Boot 3.0之后强制要求JDK 17同时底层是Jakarta EE包名从javax改成了jakarta。新项目直接上这个组合省得两年后又折腾升级。JDK 21 配 Spring Boot 3.2适合想尝鲜或者做纯新项目的但团队协作时要注意统一环境别半路有人还在用JDK 8。那问题来了IDEA 2023版本对JDK的支持情况如何我在用IDEA 2023.1和2023.2版本的时候内置的Spring Initializr已经能直接识别本机的JDK 17和JDK 21。如果你本机没有对应JDK也可以在Project SDK那里点Download JDKIDEA会帮你下载一个合适的版本。注意这里说的下载的是JDK不是JRE千万别选错了。提示Spring Boot 3.x的起步依赖里包名全部从javax.servlet换成了jakarta.servlet。早年教程里的import javax.servlet.*在SpringBoot 3里直接编译不过网上搜老教程时记得先确认版本口径。1.2 IDEA 2023到底更新了什么IDEA 2023版本相比之前最大的变化其实不是UI换肤那个花架子而是它对Spring Initializr的集成更完整了。2023年以前的IDEA创建SpringBoot项目时远程模板经常滞后会出现SpringBoot版本还停留在2.x老版本的情况。2023版本内置的模板更新及时你能在创建界面里直接选到当前稳定版本这是最直观的体验提升。另外IDEA 2023内置了更强的HTTP Client和运行面板调试SpringBoot接口的时候不用再开浏览器或者Postman去试直接在IDEA里发请求看返回效率高了不少。还有一个细节IDEA 2023.1版本开始自带的JBRJetBrains Runtime升级到了17也就是说IDEA本身运行需要JDK 17环境你本机如果再装一个JDK 8来跑老项目完全没问题两者不冲突只要你项目SDK选对就行。1.3 Maven还是Gradle我建议你先用Maven创建SpringBoot项目时构建工具一般就两个选项Maven和Gradle。新手我无脑推荐Maven原因很简单第一社区资料最多你报错时搜到的解答90%都是Maven工程第二IDEA对Maven的原生支持最成熟导入、刷新、打包都稳定第三大部分公司的存量项目都是Maven你入职后接手老代码也顺。Gradle的构建速度确实快它的增量构建和缓存机制比Maven强适合中大型多模块项目——热词里提到springboot gradle项目搭建如果你后面确实要搞多模块微服务再切Gradle也来得及初期就用Maven别给自己加戏。无论选哪个国内用户一定要配阿里云镜像不配的话首次拉取依赖能把你等急死。Maven的settings.xml里加这一段mirror idaliyunmaven/id mirrorOfcentral/mirrorOf name阿里云公共仓库/name urlhttps://maven.aliyun.com/repository/central/url /mirror2. 三种创建SpringBoot项目的方式总有一种适合你创建SpringBoot项目有三条常规路线都是正规路线没有歪门邪道。我把它们拆开细讲你按自己的情况挑一条顺手的就能走通。2.1 方式一IDEA内置Spring Initializr最推荐这是我最常用、也最推荐新手走的一条路。打开IDEA 2023点击New Project左侧项目类型列表里找到Spring Initializr注意这里IDEA可能是中文界面也可能是英文界面认准Spring Initializr这个字样就行。具体步骤展开一下在上方Project SDK那里选择你本机装好的JDK版本如果没装点旁边的Download JDK按钮让IDEA帮你下载。在Service URL那里默认是https://start.spring.io这是Spring官方提供的初始化服务可以直接用。国内访问不稳定的话可以换成阿里云的https://start.aliyun.com两个都试一下哪个加载快用哪个。填写项目基本信息Group一般用公司域名倒写比如com.exampleArtifact是你的项目名比如demoType选MavenLanguage选JavaPackaging选JarJava版本选和你JDK匹配的版本。点击Next进入依赖选择页面这里是最容易贪多的地方。新手建议先勾这几个Spring Web、Spring Boot DevTools热重启神器、Lombok省去写getter/setter。其他什么Redis、MyBatis、Seecurity先别急着勾等你有明确需求了再往里加不然项目一启动可能就因为数据库连接配置失败而退出了。点击CreateIDEA开始初始化项目右下角进度条会走一会儿这是在拉依赖。依赖下载完以后项目结构就出来了。第一次创建的时候Maven会下载大量依赖到本地仓库耗时几分钟是正常的如果很久都没反应优先检查你的Maven镜像配没配上一节已经给了配置。2.2 方式二访问start.spring.io网页初始化后导入这种方式适合IDEA版本比较旧、内置模板不好用的情况或者你想在网页端把项目信息配置得更细。我在给客户演示的时候偶尔用这种方式因为它可以直观看到SpringBoot当前版本列表。流程也很简单浏览器打开https://start.spring.io选好构建工具Maven、语言Java、SpringBoot版本、项目元信息、依赖然后点击Generate下载一个zip压缩包。把zip解压后在IDEA里File - Open选中解压出来的文件夹IDEA会把它识别为Maven项目并开始导入依赖。这一步需要耐心IDEA右下角会有一个Maven导入的进度条等它搞定。网页版的好处是省去IDEA内置向导的缓存问题而且你可以在网页上直接看到SpringBoot版本号比如当时最新的3.2.x版本在网页上一目了然。坏处是多了一步下载和解压导入操作路径长了一点。另外要提醒一句网页版生成的默认项目包里没有.gitignore如果你要用Git管理记得自己补一个。2.3 方式三纯手工搭建Maven项目训练基本功这种方式不推荐新手日常用但建议所有人都走一遍因为你总会遇到初始化失败的极端情况或者IDEA抽风没法用模板的时候。手工搭建的意义在于你会彻底明白SpringBoot项目到底是由哪些部分组成而不是只会点Next。手工搭建的步骤在IDEA里新建一个空的Maven项目不选模板不勾选任何骨架。编辑pom.xml把这个文件写完整?xml version1.0 encodingUTF-8? project xmlnshttp://maven.apache.org/POM/4.0.0 xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd modelVersion4.0.0/modelVersion parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version3.2.0/version relativePath/ /parent groupIdcom.example/groupId artifactIdmanual-demo/artifactId version0.0.1-SNAPSHOT/version properties java.version17/java.version /properties dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-test/artifactId scopetest/scope /dependency /dependencies build plugins plugin groupIdorg.springframework.boot/groupId artifactIdspring-boot-maven-plugin/artifactId /plugin /plugins /build /project这里有个关键点spring-boot-starter-parent这个父POM帮你管理好了所有SpringBoot依赖的版本你不需要自己去指定某个jar的版本号这也是SpringBoot框架的核心哲学——约定优于配置。创建启动类放在src/main/java/com/example/manualdemo下面类名叫ManualDemoApplicationpackage com.example.manualdemo; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; SpringBootApplication public class ManualDemoApplication { public static void main(String[] args) { SpringApplication.run(ManualDemoApplication.class, args); } }在src/main/resources下新建application.properties文件可以为空但建议放一个端口配置server.port8080。右键启动类选择Run看Console输出。只要能出现Started ManualDemoApplication这行说明你手工搭建成功。这套流程走完你对SpringBoot项目结构的理解会比只会点向导的人深一个层次。我当年第一次手工搭建的时候因为没有父POM管理版本手动指定了一堆版本号结果版本冲突调了半天后来才理解starter-parent的重要性。2.4 三种方式怎么选一张表给你说明白我做个简单对比你直接照着选创建方式上手难度速度适用场景IDEA内置Spring Initializr最低最快新手学习、日常开发首选网页start.spring.io低中IDEA模板异常、想可视化选版本时手工Maven项目中等慢深度理解框架原理、模板初始化失败兜底3. 从空模板到第一个接口结构、配置与运行项目创建好了接下来就是搞清楚每个文件夹是干嘛的、配置文件怎么写、以及怎么启动一个接口。这一节我按真实的开发顺序来讲。3.1 SpringBoot项目目录结构每个文件夹都是干什么的用Spring Initializr生成的项目默认就是这个结构我拆开讲一下src/main/javaJava源码目录你的启动类、Controller、Service、Mapper都放这里。包名一般是你填的Group加Artifact例如com.example.demo。src/main/resources资源目录放配置文件和静态文件。下面默认会有一个application.properties或application.yml。src/main/resources/static存放前端静态资源比如CSS、JS、图片。热词里提到vue打包放进springboot中Vue项目打包后生成的dist目录内容就是拷到这个static目录下然后SpringBoot就能直接托管前端页面了。src/main/resources/templates存放服务端模板页面比如Thymeleaf、FreeMarker的模板文件。如果你前后端分离这个目录基本用不上。src/test/java单元测试代码目录。targetMaven编译输出目录编译后的class文件和打包好的jar都会出现在这里。这里有一个热词特别典型idea为什么不显示target目录但是是存在的。这个问题后面专门讲你看到target目录消失的时候不用慌那是因为IDEA默认在项目视图里把target目录过滤掉了文件其实还在磁盘上。3.2 application.properties还是application.ymlSpringBoot的配置文件有两种格式初学者常纠结。我的建议是新项目直接用application.yml。原因很简单YAML格式通过缩进表达层级关系配置多的时候比properties清晰得多不用反复写前缀。举个实际例子配置数据源的时候properties写法是这样的spring.datasource.urljdbc:mysql://localhost:3306/test spring.datasource.usernameroot spring.datasource.password123456换成YAML写法spring: datasource: url: jdbc:mysql://localhost:3306/test username: root password: 123456一眼就能看出层级的优劣。不过要注意YAML对缩进极其敏感同一个key下的子项缩进必须一致否则启动就会报解析错误。还有几个配置是2023年开发必用的server: port: 8080 servlet: context-path: /api spring: application: name: demo-service profiles: active: devserver.port不用说是改端口context-path是给所有接口加统一前缀spring.application.name是服务名微服务里特别重要spring.profiles.active是激活对应的环境配置文件比如你同时有application-dev.yml和application-prod.yml通过这个参数切换环境不用改代码。3.3 写一个Controller并启动5分钟看到结果项目能启动之后第一步先写个Controller验证全链路通不通。在src/main/java/com/example/demo下新建一个controller包包里新建HelloController.javapackage com.example.demo.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这个注解是Controller和ResponseBody的合体表示这个类里的每个方法返回的都是字符串或JSON不走视图渲染。GetMapping(/hello)表示把方法映射到HTTP的GET请求路径/hello上。然后右键启动类选择Run看到控制台输出Tomcat started on port(s): 8080 (http)这行之后浏览器访问http://localhost:8080/hello页面上出现Hello, Spring Boot!恭喜你整套环境已经从零跑通了。这里提醒一下IDEA 2023部分版本默认开启了HTTP Client面板你直接在编辑窗口里的请求URL旁边点运行也可以效果和浏览器一样。注意启动类一定要放在最外层包也就是所有Controller、Service所在包的父级目录。因为SpringBootApplication默认扫描的是启动类所在包及其子包如果启动类放错位置Controller再怎么写都访问不到而且控制台不会报错只会显示404这个坑我见人踩过无数次。4. 我踩过的坑常见错误与排查实录这部分内容是重头戏我把这些年实际带人过程中遇到的高频问题整理一下每一个都有对应的场景和排查思路建议收藏备用。4.1 端口被占用与IDEA的Cannot start internal HTTP server先讲一个绝大多数人都遇过的经典错误启动项目时报错Port 8080 was already in use或者IDEA面板弹红字Cannot start internal HTTP server。前者好解决是8080端口被其他进程占用要么换个端口要么找到占用进程杀掉。但后者Cannot start internal HTTP server严格来说和你的项目代码无关它是IDEA内部的一个HTTP服务启动失败常见于IDEA安装时修改过默认配置、系统代理设置异常、或者某次IDEA异常退出后内部状态紊乱。一个比较有效的排查方法是File - Settings - HTTP Proxy把代理设置改成No proxy然后重启IDEA。多数情况下这个报错和代理配置有关。另外一个和上面的报错容易混淆的情况是IDEA的左下角Services面板里如果你之前把Tomcat Server或者SpringBoot项目以外部Tomcat方式配置过IDEA会尝试启动外部Tomcat此时如果Tomcat路径配置不对也会报错。注意SpringBoot自带的是内嵌Tomcat你不需要额外安装和配置任何Tomcat Server这也是热词里idea 2026本地部署tomcat9没找tomcat server那个问题的本质——根本不需要找SpringBoot已经内置了。想改端口直接在application.yml里改就行。4.2 SpringBoot版本太高引发的兼容性问题热词里有springboot版本太高这个说法这不是调侃是个真实痛点。SpringBoot 3.0发布后很多老开源库还没有适配比如某些版本的MyBatis、ShardingSphere、Dubbo它们的SpringBoot 2.x版本在SpringBoot 3.x环境下启动就会直接链路报错最常见的就是NoSuchMethodError或者ClassNotFoundException。我的建议是如果你是新项目且依赖比较简单直接用3.x没问题但如果你依赖的第三方库版本较老、维护也不活跃建议老老实实用SpringBoot 2.7.x搭配JDK 8团队协作时把这些版本写进项目的README里避免不同人用了不同版本出现在我电脑上能跑的尴尬局面。如何查看当前项目SpringBoot版本直接在pom.xml的parent节点里看version标签或者执行mvn dependency:tree就能看到全部依赖版本树。4.3 IDEA导入本地JAR包的两种正确姿势热词里idea怎么导入jar包这个问题我每次带新人都会被问一次。分为两种情况情况一这是个普通Java项目没有Maven管理。操作路径是File - Project Structure - Modules - Dependencies点加号选择JARs or directories选中你本地的jar包Apply之后项目就能引用这个jar里的类了。这种方式只对当前项目生效。情况二这是个SpringBoot Maven项目推荐方式。本地jar不要手动导入先把它安装到本地Maven仓库然后在pom.xml里声明依赖。安装命令是mvn install:install-file -Dfile/path/to/your.jar -DgroupIdcom.example -DartifactIdexample-jar -Dversion1.0.0 -Dpackagingjar执行完以后在pom.xml里加对应依赖。这样做的最大好处是项目换台电脑、拉下来就能构建不用每个人都手动导一遍jar。很多新手把本地jar手动导入到IDEA后代码能跑了但同事拉代码却编译不过就是因为jar没有进Maven仓库这种坑不是一次两次了。4.4 target目录明明存在却不显示热词里那句idea为什么不显示target目录,但是是存在的我深有体会。两种情况第一种是因为IDEA默认在Project视图里隐藏了target目录你在项目面板里看不到它但在IDEA的终端或者系统文件管理器里又能看到。解决办法是在Project视图右上角有个齿轮图标点开选Project Structure或者直接按Alt1切到Project视图后在顶部下拉框选Project视图模式如果还看不到检查File - Settings - Editor - File Types里有没有把target目录注册成忽略文件。第二种是Package视图的影响。如果你用的是Package视图它是按包名展示的target目录当然不会出现。切回Project视图就行。顺带说一句target目录是Maven编译后生成的产物目录你完全不需要手动去管它跑一次mvn compile或者mvn package之后它自然就出来了。如果项目改了代码但target里还是旧的那就是没触发重新编译执行一下Build - Rebuild Project就能解决。4.5 其他高频问题的速查表还有一些问题属于遇见一次就知道怎么回事的我直接整理成表格方便你速查报错现象原因与解决方法Cannot resolve symbol SpringApplicationMaven依赖没下完或者IDEA索引出问题。先等右下角Maven导入完成然后File - Invalidate Caches / Restart清缓存重启Failed to configure a DataSource勾选了数据库依赖但没配数据库连接信息。解决办法加上数据源配置或者暂时把数据库依赖从pom里移除No active profile set, falling back to default只是提示没激活profile不算报错。在application.yml里设置spring.profiles.active即可消除ClassNotFoundException: javax.servlet.*SpringBoot 3.x下使用了老代码。把javax.servlet换成jakarta.servletAddress already in use端口被占用。改端口或杀进程JDK版本不匹配报错IDEA的Project SDK和pom.xml里的java.version不一致统一改为相同版本Cannot download start.spring.io网络问题。切换到阿里云Initializr地址或检查网络排查问题的核心思路是先看Console里第一行报错不是中间那一大坨异常栈的某一行先看项目配置pom、yml、JDK版本再看环境端口、代理、IDEA状态。很多时候新手被报错吓住其实SpringBoot的日志已经把原因写得很明确了从下往上翻找到第一句带Caused by的地方那才是病根。最后聊几句实在话创建SpringBoot项目这件事本身不是什么高深技术但它卡住了很多人问题往往出在版本搭配和环境理解上。我个人这几年的习惯是新项目一律SpringBoot 3.x JDK 17 Maven YAML配置依赖能少勾就少勾用到再加遇到问题先看启动日志的Caused by不要凭感觉乱改。你把这篇文章里的流程走完两三遍后面再看到什么SpringBoot整合Flink、“SpringBoot自定义自动配置这些进阶话题底气就完全不一样了因为你的地基已经踩实了。要是创建过程中还有哪个报错解决不了把报错原文发出来我看到会回复。