说起在 IDEA 里创建一个 SpringBoot 项目很多人觉得这是再基础不过的开局操作。但我给团队做新人培训时发现十个新手里有七个会在这一步卡住——不是卡在代码层面而是卡在版本匹配、依赖下载、Maven 仓库这些“看起来不是问题的问题”上。IDEA 版本不对、JDK 版本不匹配、Spring Boot 版本选太高、镜像源没配随便一个都能让你在“写第一行代码之前”折腾半小时。这篇教程就是要把这些前置坑提前拆给你看从环境准备到项目跑起来、再到第一次在浏览器里看到接口返回一条线走完。适合刚接触 Spring Boot 的初学者也适合那些之前用 Eclipse 或其他编辑器、刚切换到 IDEA 的开发者。1. 开工前的三件套JDK、IDEA、Maven 的版本怎么选才不闹心1.1 JDK 版本Spring Boot 2.x 和 3.x 的分水岭创建 Spring Boot 项目之前先确认 JDK。这是最容易出问题的环节因为你电脑上装的 JDK 版本直接决定了你能用哪个版本的 Spring Boot。Spring Boot 2.x 系列比如 2.7.x最低要求 JDK 8往上兼容到 JDK 17 甚至 21。而 Spring Boot 3.x 系列最低要求 JDK 17。也就是说如果你本机装的是 JDK 8却选了一个 Spring Boot 3.2 的版本那项目创建完大概率编译报错报错信息还特别含糊——什么UnsupportedClassVersionError新人一看就懵根本想不到是版本不匹配。我的建议很直接如果你是跟着老项目走或者公司技术栈锁定在 JDK 8那 Spring Boot 选 2.7.x 就好。如果是从零开始学新东西建议直接 JDK 17 Spring Boot 3.x因为 3.x 已经是主流相关的资料、新特性、社区讨论都在这边。如果你装的是 JDK 21 这种最新版也没问题Spring Boot 3.2 以上对 JDK 21 支持得很好。怎么查自己电脑的 JDK 版本打开终端或 CMD 输入java -version输出里会直接显示版本号比如openjdk version 17.0.8或java version 1.8.0_202。注意JDK 8 的版本号显示是1.8开头别把它当成 1.8 版本还在 JDK 1.x 时代这就是 JDK 8。如果你还没有 JDK去 Oracle 官网下载就行注意选择对应操作系统的安装包。不想用 Oracle JDK 的话OpenJDK 也完全够用两者的区别在这个场景下基本感受不到。还有一个重点记住你安装的 JDK 路径后面在 IDEA 里配置项目 SDK 时要手动选。1.2 IDEA 版本社区版够用吗哪个版本才不算“过时”IDEA 分为 IntelliJ IDEA Ultimate旗舰版和 IntelliJ IDEA Community社区版。很多人担心社区版功能不全实际上对于创建一个 Spring Boot 项目来说社区版完全够用。社区版和旗舰版在 Spring Boot 开发上的主要区别在于对 Spring 框架的专用支持。旗舰版有一个 Spring Assistant 或者叫 Spring 项目脚手架的内置支持创建 Spring Boot 项目时图形化操作更顺畅可以直接在界面里勾选依赖。社区版这边创建项目时没有那个专门的 Spring 向导但我们可以采用另外两种方式达到同样的效果后面我会详细说。也就是说社区版只是多两步操作不耽误事。关于 IDEA 版本本身我建议你用最新稳定版。IDEA 官方每年会发一个大版本比如 2023.1、2023.2每个大版本里又有 Update。新版本对高版本 JDK 的支持、对 Maven 的兼容性都更好。如果电脑配置一般运行最新版可能有卡顿那退而求其次选择 2022.3 或 2023.1 也完全没问题。提示如果你之前已经装了 IDEA可以在 Help → About 里看版本号。如果版本过旧比如 2020 或 2021建议升级否则后面创建 Spring Boot 3.x 项目时会遇到内置运行环境不支持的情况。1.3 Maven 配置IDEA 自带的 Maven 和镜像源设置创建 Spring Boot 项目后IDEA 会通过 Maven 下载一大堆依赖 jar 包。这里有一个关键点IDEA 内置了 Maven但你最好不要直接用它原因很简单——内置 Maven 的配置文件默认指向中央仓库在国内网络环境下下载依赖奇慢无比一个spring-boot-starter-web就能让你等到怀疑人生。解决办法配置一个好用的镜像源。具体操作分两步。第一步找到你本机 Maven 的配置文件。如果你没有单独安装 MavenIDEA 内置的 Maven 在 IDEA 安装目录下的plugins/maven/lib/maven3/conf/settings.xml。如果你自己装过 Maven就是%MAVEN_HOME%/conf/settings.xml或~/.m2/settings.xml。第二步在mirrors节点里加一段阿里云镜像配置mirror idaliyunmaven/id mirrorOfcentral/mirrorOf name阿里云公共仓库/name urlhttps://maven.aliyun.com/repository/public/url /mirror然后在 IDEA 里打开设置File → Settings → Build, Execution, Deployment → Build Tools → Maven把 User settings file 指向你配置好的那个 settings.xml。这样依赖下载速度会快一个数量级。IDEA 自带的 Maven 和本地 Maven 具体用哪个我倾向于用 IDEA 自带的但配置文件用自己修改过的那份相当于既享受了内置的便利又拿到了自定义配置的加速效果。如果你单独安装了 Maven直接在 IDEA 里指定你的 Maven home 路径就行。2. 创建项目的两条路内置向导和 Spring Initializr 网页端差别在哪2.1 IDEA 内置向导的完整操作流程如果你用的是旗舰版 IDEA或者社区版装了 Spring Assistant 插件可以直接用内置向导。打开 IDEA选择 New Project或者 File → New → Project左侧列表找 Spring Initializr。这里有四个关键字段要填Name项目名一般全小写多个单词用中划线分隔比如demo-project。Location项目存放路径建议单独建一个文件夹统一管理代码。Type选择 Maven默认就是这个。Group公司或组织的域名倒写比如com.example。这个会变成包路径的一部分。JDK下拉框里选择前面确认好的 JDK 版本。填完之后点 Next进入依赖选择页面在左侧搜Spring Web勾选上再按需勾选其他依赖这个后面单独讲。然后点 Create 或 FinishIDEA 会自动联网生成项目骨架并开始下载依赖。这个过程如果顺利右下角会出现一个依赖下载的进度条。下载完成后左侧目录结构会变成标准的 Maven 工程结构pom.xml文件也生成了。2.2 用 Spring Initializr 网页端创建适合社区版用户社区版没有内置 Spring Initializr 引导但这其实不是问题。打开浏览器访问https://start.spring.ioSpring 官方提供的初始化服务这个页面就是一个完整的项目生成器。页面上需要填的信息和 IDEA 内置向导几乎一模一样Project 选 MavenLanguage 选 JavaSpring Boot 版本选一个稳定版别选带有SNAPSHOT或RC字样的Group 填com.exampleArtifact 填项目名。右侧的 Dependencies 区域点 Add Dependencies搜索Spring Web并添加。填完点 Generate浏览器会下载一个 zip 压缩包。解压后用 IDEA 的 File → Open 打开这个文件夹选择信任项目Trust ProjectIDEA 识别到pom.xml后会自动把它作为一个 Maven 项目导入并下载依赖。这两条路的最终结果完全一样区别只在于项目骨架是 IDEA 生成的还是网页端生成的。我个人的习惯是直接用网页端因为里面对 Spring Boot 版本的展示更直观还能提前看到依赖列表比较省事。IDEA 内置向导适合不想切浏览器的场景。2.3 Group、Artifact、包名的讲究新手在填这些字段时觉得无所谓但其实它们决定了你后面写代码的包结构。始终理解一个原则Group 是组织标识Artifact 是项目标识两者拼起来就是 Maven 仓库里这个项目的坐标。一个典型的项目坐标groupIdcom.example/groupId artifactIddemo-project/artifactId version0.0.1-SNAPSHOT/version生成的项目里会有这样一个包路径com/example/demo_project。这里有一个小细节如果 Artifact 里带中划线生成的包名的中划线可能会被去掉或转为下划线这是正常的。后面你创建 Controller、Service 这些类时都放在这个包下面不要乱放。这里还要注意一个点不少人会把 Group 写成com.公司名.部门名这没问题但最好从一开始就统一规范因为一旦项目启动包名改起来非常痛苦涉及大量移动文件的操作。3. 依赖勾选背后的逻辑Spring Web 之外你到底需要什么3.1 Spring Web让项目拥有 Web 服务能力创建项目时依赖列表里最核心的就是Spring Web。这个依赖会引入内嵌的 Tomcat 服务器、Spring MVC 框架以及其他 web 支持。勾选之后你的项目才具备启动 HTTP 服务、处理请求、返回 JSON 数据的能力。用一个生活化的类比Spring Web 就是你项目的“快递收发室”。它负责接收外部来的请求快递然后路由给你写的 Controller收件人再把返回值回执封装成 HTTP 响应发给客户端。如果没有这个依赖项目启动了也只是一个空壳没有任何对外服务能力。很多初学者在这里会犯一个选择困难症依赖列表那么长到底该勾哪些我的建议很简单第一次跑通项目只勾 Spring Web 就够其他什么都不用加。等后面确实用到某个功能时再手动往pom.xml里加依赖就行。Maven 支持随时加依赖不用一开始就面面俱到。3.2 几个常用依赖的适用场景虽然我建议新手先只勾 Spring Web但了解其他常见依赖的用途还是有必要的因为你在看别人项目时会频繁遇到它们。依赖作用备注Spring Boot DevTools热部署改代码后自动重启开发利器实测很好用Lombok简化实体类代码自动生成 getter/setter、构造器等需要安装 Lombok 插件Spring Data JPA操作数据库的 ORM 框架适合快速开发MyBatis Framework另一款数据库访问框架国内使用极广与 Spring Data JPA 二选一MySQL Driver连接 MySQL 数据库的驱动用 MySQL 时必须加Thymeleaf服务端模板引擎做页面渲染时用Spring Security认证授权框架项目成熟后再考虑不是让你全部勾上而是要理解依赖这个东西是按需引入的勾得越多项目启动越慢攻击面也越大。比如你只是做一个给 App 提供 JSON 数据的后端接口那 Thymeleaf 这个模板引擎就完全没必要引入。3.3 pom.xml 里发生了什么创建完项目后打开pom.xml看一下里面核心结构是这样的parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version3.2.0/version relativePath/ /parent dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency /dependencies build plugins plugin groupIdorg.springframework.boot/groupId artifactIdspring-boot-maven-plugin/artifactId /plugin /plugins /buildspring-boot-starter-parent是 Spring Boot 的父工程它统一管理了所有 starter 的版本号。这就是为什么你在依赖里不需要写 Spring Web 的版本号——父工程已经帮你管好了。这种设计叫“依赖版本集中管理”能有效避免不同依赖版本冲突。spring-boot-starter-web是 web 场景的启动器它本身不带代码但会把 Spring MVC、内嵌 Tomcat、Jackson JSON 处理库等一系列必要依赖都传递引进来。这也是 Spring Boot 简化配置的精髓你引入一个 starter等于配好了完整的一套能力。spring-boot-maven-plugin是打包插件没有它你无法将项目打包成可执行的 jar 包。这个插件默认执行目标把依赖和项目本身打成一个可执行的 fat jar。4. 把项目跑起来从启动日志到浏览器看到接口返回4.1 认识 IDEA 里生成的目录结构项目创建完成后IDEA 左侧的目录结构长这样demo-project/ ├── src/ │ ├── main/ │ │ ├── java/ │ │ │ └── com/example/demo_project/ │ │ │ └── DemoProjectApplication.java │ │ └── resources/ │ │ ├── static/ │ │ ├── templates/ │ │ └── application.properties │ └── test/ │ └── java/ │ └── com/example/demo_project/ │ └── DemoProjectApplicationTests.java ├── pom.xml └── .idea/DemoProjectApplication.java是启动类里面就几行代码但整个 Spring Boot 项目的启动都靠它。resources目录放配置文件、静态资源和模板文件。static目录放静态页面、JS、CSStemplates目录放模板引擎文件application.properties是核心配置文件。test目录放测试代码。启动类长这样package com.example.demo_project; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; SpringBootApplication public class DemoProjectApplication { public static void main(String[] args) { SpringApplication.run(DemoProjectApplication.class, args); } }SpringBootApplication是一个组合注解包含SpringBootConfiguration、EnableAutoConfiguration和ComponentScan。它标记这个类是应用的入口Spring Boot 会扫描这个类所在包及其子包的组件。这就是为什么 Controller 不能放在这个包外面放在外面 Spring 扫不到接口就会 404。4.2 写第一个 Controller项目能启动之后我们写一个简单的接口来验证整个链路是否打通。在启动类所在的包下新建一个controller子包再在子包里创建一个HelloController.javapackage com.example.demo_project.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 请求的控制器并且默认将返回值直接写入 HTTP 响应体也就是返回纯文本或 JSON。GetMapping(/hello)表示这个方法处理 GET 请求路径是/hello。这里要特别注意包路径。HelloController放在com.example.demo_project.controller包里而启动类在com.example.demo_project包里这样 Spring Boot 的组件扫描能扫到它。如果你把 Controller 放到com.other这种与启动类不相关的包下启动类注解里的ComponentScan默认扫描范围就不覆盖它接口会直接 404。4.3 启动项目与日志解读在 IDEA 里点开DemoProjectApplication点击类名左侧的绿色三角形箭头选择 Run。也可以右键运行。看到控制台开始刷日志时不要慌等它刷完。第一次启动时因为要加载全部依赖可能耗时较长。启动成功的标志是类似下面的日志Tomcat started on port(s): 8080 (http) with context path Started DemoProjectApplication in 2.345 seconds (process running for 2.789)看到Tomcat started on port(s): 8080就说明 Web 服务器已经起来了。Started DemoProjectApplication in 2.345 seconds表示应用启动完成。稍等片刻浏览器访问http://localhost:8080/hello页面会看到Hello, Spring Boot!到这一步你的第一个 Spring Boot 项目就正式跑通了。从创建项目到浏览器看到自定义内容这条链路是 Spring Boot 开发里最基础也是最核心的闭环。后面所有的 CRUD、对接数据库、写业务逻辑都是在这个闭环上加码。5. 新手最容易踩的坑与排查思路5.1 端口被占用那个“8080 already in use”的报错启动项目时如果控制台报Web server failed to start. Port 8080 was already in use那说明 8080 端口已经被另一个进程占用了。新手第一次遇到这个报错很慌其实它是最容易解决的问题。排查链路先确认谁占用了端口然后杀掉它或者给项目换个端口。在 Windows 下打开 CMD 运行netstat -ano | findstr 8080输出的一行里会显示 PID比如最后一列是 12345。再运行taskkill /PID 12345 /F就能把占用进程杀掉。如果是 Linux 上命令是lsof -i:8080杀掉进程后重新启动项目即可。另一个思路是给项目换端口。在application.properties里加一行server.port8081这样项目就会从 8081 端口启动。如果你同时跑多个 Spring Boot 项目这个操作更常用。5.2 依赖下载失败反复报红竖弯的 Maven 错误创建完项目后如果pom.xml里出现红色波浪线或者External Libraries里看不到依赖多半是依赖没有成功下载。这在国内网络环境下太常见了。最常见的现象是 IDEA 右下角一直转圈Maven 仓库里不断出现*.lastUpdated后缀的文件这些是下载失败后留下的缓存标记。解决方法分两类一类是配置阿里云镜像也就是前面 1.3 节提到的这是在源头上解决问题另一类是手动删除本地 Maven 仓库中所有*.lastUpdated文件然后 Reimport。IDEA 里点一下右侧 Maven 面板的刷新按钮Reload All Maven Projects就行。如果还不行删掉本地仓库里那些失败的目录后重新刷新。本地仓库默认位置是C:\Users\你的用户名\.m2\repository删错的风险不大。注意不要去改 Spring Boot 的版本号来迁就依赖下载失败。很多新手看到报错第一反应是把版本降级结果越降越乱。先排除镜像源和网络问题再考虑版本问题。5.3 版本不匹配JDK 与 Spring Boot 的隐性冲突这个问题隐蔽性很强报错信息往往不是直接的“版本不兼容”而是像Unable to import maven project: See logs for detailsInvalid source release: 8编译时出现大量红色波浪但代码看起来没问题排查链路点击 File → Project Structure → Project Settings → Project确认 Project SDK 和 Language Level 是否匹配。比如你的 JDK 是 17但 Language Level 选的 8编译就会报Invalid source release: 8。再确认 Maven 的 JDK 设置。File → Settings → Build Tools → Maven → Runner看 JRE 是不是也指向了正确版本。这一步很多人忽略因为 IDEA 有多个“当前 JDK”的概念Project SDK 一个、Maven Runner JRE 一个、模块的 SDK 一个任何一个不对都会引发莫名其妙的问题。5.4 包扫描不到的坑启动类位置放错了这个坑我在 4.2 节提过但还是要单独拿出来强调因为它几乎是新手必踩。Spring Boot 默认会扫描启动类所在包及其子包下的所有组件如果你把 Controller 放在启动类的包外面启动时不会报错但浏览器访问就是 404排查起来完全没有思路因为控制台非常干净什么错都不报。检查方法看你的启动类在哪一层包Controller/Service 这些类必须在它的子包下。比如启动类是com.example.demo_project.DemoProjectApplication那其他类必须在com.example.demo_project或com.example.demo_project.xxx下。5.5 首次启动慢不用怀疑自己的电脑坏了第一次启动 Spring Boot 项目时因为需要加载很多类和引用资源耗时可能在 5 到 10 秒以上这是正常的。如果启动时控制台输出了一堆 DEBUG 日志可能是日志级别配置的问题不影响使用。真正值得注意的是启动过程中 Maven 还在后台下载依赖的情况。这样项目启动会被阻塞看起来像卡死了其实是在等 Maven 下载完依赖。解决办法还是回到 1.3 节的镜像源配置上依赖下载飞快启动自然就顺。6. 让项目更顺手的几个配置端口、Banner、热部署6.1 application.properties 与 application.yml 的选择Spring Boot 支持两种配置文件格式application.properties和application.yml。两者的功能等价但语法风格不同。很多老前辈倾向于用 yml因为它的层级用缩进表示嵌套结构看起来更清晰新人则更容易接受 properties 的键值对格式因为不需要纠结缩进对齐。两种格式我都用过长期下来更推荐.properties。理由很简单完全不需要介意缩进问题而且 IDEA 对 properties 的自动补全和跳转支持更成熟。不过你接手别人的项目时两种格式都会遇到所以至少要能看懂.yml的写法。比如配置端口和上下文路径.properties写server.port8080 server.servlet.context-path/api.yml写server: port: 8080 servlet: context-path: /api注意.yml里冒号后面要有一个空格否则解析报错。6.2 Banner让你的项目启动有点仪式感Spring Boot 启动时控制台会打印一个巨大的 ASCII Art Logo默认是 Spring 的图标。很多开发者会把它替换成自己项目的 Banner算是一种小小的仪式感也能在团队里区分不同服务。生成 Banner 可以用在线 Banner 生成器比如 patorjk.com 的 Text to ASCII Art Generator输入你想展示的文字生成出 ASCII 图后复制。然后到src/main/resources目录下新建一个banner.txt文件把生成内容粘贴进去重新启动项目就能看到效果。这里有一个小技巧在 Banner 文本里可以加上变量比如$(spring-boot.version)、$(application.title)这种Spring Boot 会自动替换成实际值。用这个方式把版本信息放到控制台启动时一眼就能确认版本是否正确排查环境问题时非常省事。6.3 DevTools 热部署改代码不用重启开发过程中每次改代码都要手动重启项目非常打断思路。引入 Spring Boot DevTools 可以解决这个问题。它的原理并不复杂监控 classpath 下的文件变化发现变化后自动重启应用整个过程只需要一两秒。要使用的话在pom.xml里加入dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-devtools/artifactId optionaltrue/optional /dependencyoptional设为true的作用是让这个依赖不传递到依赖本项目的外部模块避免把开发用的热部署功能打包进生产环境。加完依赖后IDEA 里还需要一步设置File → Settings → Build, Execution, Deployment → Compiler勾选 Build project automatically。再打开高级设置Settings → Advanced Settings勾选 Allow auto-make to start even if developed application is currently running。这步设置做完修改代码后 IDEA 自动编译DevTools 监听到变化就会自动重启开发体验会提升一大截。这里提醒一句DevTools 是开发阶段用的工具不要用它替代生产环境的部署方案。生产环境打包时它不会生效因为它只存在于optional的开发依赖里。6.4 多环境配置开发、测试、生产分开管理最后说一个很实用但新手接触不到的配置——多环境管理。Spring Boot 支持通过配置文件名后缀实现多环境切换例如application-dev.properties开发环境application-test.properties测试环境application-prod.properties生产环境然后在application.properties里指定当前使用哪个环境spring.profiles.activedev这样启动时会加载application-dev.properties而公共配置放在application.properties里。数据库连接地址、端口号、日志级别这些不同环境的差异化配置都可以按环境拆开避免每次部署都要手动改配置。切换到不同环境时只需要改spring.profiles.active的值就行或者启动时通过参数指定java -jar demo-project.jar --spring.profiles.activeprod在这套机制下项目配置文件会清爽很多不会出现一堆注释掉的历史配置。我个人的体会是创建 Spring Boot 项目这件事本身没什么高深的技术含量但它像是盖楼前的地基。地基打得稳后面写接口、连数据库、对接 Redis、集成消息队列的时候少出一堆环境问题地基打得草率JDK 版本和框架版本不匹配、Maven 仓库不通、热部署没配好这些小问题后面会反复回来找你麻烦。特别是当你从复制粘贴别人的代码转向自己从零搭建项目时动手走一遍完整流程对 Spring Boot 的运行机制理解会上一整个台阶。所以哪怕你已经会创建项目了也建议按这篇教程的链路重新走一遍重点把版本选型、镜像源配置和多环境管理的习惯建立起来这会让你后续的 Spring Boot 开发顺畅很多。