峰瑞资本很多同学第一次打开 Spring Initializr 页面时，第一反应大概率是：选项也太多了吧。构建工具选 Maven 还是 Gradle，语言是 Java 还是 Kotlin，Spring Boot 版本到底跟不跟最新，依赖那一长串列表里到底选什么——还没开始写代码，光是在这一屏配置上就能纠结二十分钟。尤其是想快速上手 Spring Boot 3.x 的新人，面对这套全新的版本体系，稍不留神就会生成一个启动报错的项目。
这个系列前面两篇已经聊过 Spring Boot 的整体轮廓和生态组件，今天这篇就落到实操最前端：用 Spring Initializr 把 Spring Boot 3.x 项目骨架搭起来。Spring Initializr 并不是一个普通的“脚手架模板”，它背后带有一套完整的版本兼容校验和依赖管理逻辑，理解清楚它，你后续每一次新建项目、升级版本都会顺很多。这篇文章会覆盖创建项目的全部路径、关键配置项的选择逻辑、生成后的目录结构解读、本地运行验证，以及我这两年带项目时实测踩过的几个高频坑。不管你是刚入门想跑通第一个接口，还是团队里要统一项目生成规范，这篇都值得收藏着按步骤走一遍。
1. Spring Boot 3.x 的版本变化，以及为什么必须用 Initializr
1.1 3.x 相比 2.x 的三个核心差异
如果你之前用过 Spring Boot 2.x，直接切到 3.x 的时候会明显感到三处不同。
第一，Java 版本基线直接从 Java 8 跳到了 Java 17。这是很多人第一次创建 3.x 项目时最容易踩的坑：明明本机有 JDK 8，生成的代码一编译就报错。Spring Framework 6 和 Spring Boot 3.x 的底层字节码全部基于 Java 17 构建，这意味着你本机、CI 服务器、部署环境都必须是 JDK 17 或者更高版本，低于这个版本连依赖都拉不下来。
第二，javax 命名空间整体迁移成了 jakarta。过去写 import javax.servlet.http.HttpServletRequest，Spring Boot 3.x 里要改成 import jakarta.servlet.http.HttpServletRequest。这个迁移对老项目来说是笔不小的改造工作量，但对新项目反而是好事——你从一开始就站在了正确的命名空间上，以后跟着版本升级不会遇到兼容性烂摊子。
第三，对 GraalVM 原生镜像的支持从实验性变成了正式能力。Spring Boot 3.x 可以把应用直接编译成原生可执行文件，启动时间从秒级缩短到毫秒级，内存占用也大幅下降。虽然原生镜像目前还不适合所有场景，但它标志着 Spring Boot 的部署形态开始分化：传统 JVM 模式和云原生模式并行。如果你创建项目时看到 Native Build Tools 相关选项，不要慌，默认不勾选就完全不受影响。
这些变化叠加在一起，意味着在 Spring Boot 3.x 时代，你不能再靠“从旧项目复制一份改改”的老办法来建项目了。最稳妥、最省事的路径就是用 Spring Initializr 从源头生成一个干净、兼容、版本正确的骨架。
1.2 Initializr 解决的远不止“生成目录”这么简单
很多人容易把 Spring Initializr 理解成“一个帮你创建文件夹和代码模板的工具”，这个认知不仅片面，还挺危险。Spring Initializr 真正的价值在于：它会根据你选择的 Spring Boot 版本，自动校验依赖之间的兼容组合关系。
举个例子，你在网页上同时勾选了 spring-boot-starter-data-jpa 和 spring-boot-starter-security，然后在 Spring Boot 3.2.x 版本下生成，Initializr 给出的依赖版本都是经过官方测试矩阵验证的。但如果你自己从网上找一篇博客照着复制 pom 依赖，很可能把 2.7 版本的 spring-boot-starter-parent 和 3.2 版本的某个 starter 混在一起，最终项目能正常编译，启动时报一堆 ClassNotFoundException，排查起来极其痛苦。
另外，Spring Initializr 本身也是一个开源项目，它提供的服务不光是网页端，还开放了 HTTP API。这意味着你可以把它接入到自己的内部平台、命令行工具、甚至 IDE 插件里，让团队每个人创建出来的项目都遵循同一套规范和依赖基线。对技术管理者来说，这是一件很值得投入的事情：与其在团队 wiki 里写一堆“新建项目时请选择某某版本、某某依赖”，不如统一封装一套生成脚本，让 Initializr 从源头兜底。
从 2014 年 Spring Initializr 上线到现在，它已经成了 Spring 生态里使用率最高的工具之一，原因不是它界面有多惊艳，而是它真正把“项目初始化”这件看似简单、实则充满版本兼容暗坑的事情，做成了标准化流水线。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 创建项目的四条路径，选一条顺手的就别纠结了
2.1 start.spring.io 网页版：最直观，适合新手和快速验证
网页版的入口是 start.spring.io，我用它创建项目已经不下几百次了。它最大的优点是所见即所得：左边一排配置项，右边实时显示项目类型、语言、Spring Boot 版本和依赖列表，中间底部甚至能预览生成后的项目结构。
操作流程很简单：左侧填好 Group（通常是公司域名倒写，比如 com.example）、Artifact（项目名，比如 demo），选好构建工具、语言、Spring Boot 版本和 Java 版本，右侧点击“ADD DEPENDENCIES”搜索并添加你要的 starter 依赖，最后点“GENERATE”按钮，浏览器就会下载一个 zip 压缩包。解压后用 IDE 打开，项目直接能用。
这里有一个小技巧：网页版右上角的依赖搜索框里输入关键词，会展示所有包含该关键词的 starter 及其简短描述。但一定要注意，有些依赖名称看着相似，实际用途完全不同。比如你输 web，会看到 Spring Web 和 Spring Web Services，前者是构建 MVC 和 RESTful API 的核心，后者主要用于 XML 格式的 SOAP Web Service。新手如果不细看就勾选，项目里会混进一堆用不到的类库。
2.2 IDEA 内置的 Spring Initializr 向导
如果你用的是 IntelliJ IDEA，新建项目时左侧选择“Spring Initializr”或者新版 IDEA 里的“Spring Boot”，本质上调用的还是 start.spring.io 的服务。它和网页版的配置项几乎一一对应，区别只在于生成的目录会直接落在你的工程里，IDEA 会自动识别为 Maven 或 Gradle 项目，省去了下载 zip、解压、再导入的步骤。
但用 IDEA 内置向导有两点要留意。第一，IDEA 版本会缓存部分 Spring Boot 版本列表，偶尔会滞后于官网。如果你在网页版上看到某个刚发布的新版本，IDEA 里却迟迟不显示，别慌，这通常不是版本没发布，而是 IDEA 的版本列表还没刷新。第二，如果你在无网络环境或者公司内网部署了私有 Nexus 仓库，IDEA 内置向导可能连不上 start.spring.io，此时要用网页版生成 zip，然后手动移到目标机器上解压导入，或者干脆用后面提到的命令行方式。
2.3 用 curl 一行命令创建：适合脚本化和团队标准化
很多人不知道，start.spring.io 不只是网页，它的背后是一套 REST API。你完全可以用命令行来生成项目：
bash复制curl -s https://start.spring.io/starter.zip \
-d type=maven-project \
-d language=java \
-d bootVersion=3.3.1 \
-d groupId=com.example \
-d artifactId=demo \
-d name=demo \
-d packageName=com.example.demo \
-d packaging=jar \
-d javaVersion=17 \
-d dependencies=web,actuator \
-o demo.zip
执行完这行命令，当前目录下就会多出一个 demo.zip。拆开之后，项目结构和网页版生成完全一致。dependencies 参数用逗号分隔，每个依赖对应一个短 ID，这个短 ID 可以从网页版添加依赖时 URL 里的参数看，也可以通过元数据接口查询：
bash复制curl https://start.spring.io/metadata/client
这个返回结果里会有所有支持的依赖 ID，以及 groupId、artifactId、版本范围等等，信息量很大。如果你后续要做公司内部脚手架平台，这个接口可以说是最重要的信息来源。
命令行方式还有一个隐藏优势：它可以被写进脚本里，批量生成多个同构项目，或者在 Git 仓库里保留一份文档化的创建命令，这样团队里任何人想新建一个模块，只要照着命令改参数，出来的项目就不可能和别人有结构性差异。
2.4 怎么选择适合自己的路径
我个人的建议是：如果你是刚学习 Spring Boot、想有个项目练手，直接用网页版 start.spring.io，把下载的 zip 解开后拖进 IDEA 看一遍代码结构，这个流程走一次会对项目结构有非常直观的认知。如果你每天都要在 IDEA 里新建项目做功能验证，就用 IDE 内置向导，省事。如果你负责团队基础架构，或者需要频繁创建雷同的微服务模块，那一定要把命令行方式用起来，把它固化成团队脚本，效率和规范性都会有质的提升。
3. 新建项目时真正需要判断的几个关键配置
3.1 构建工具：Maven 还是 Gradle
这是新建项目时第一个选择题。Spring Initializr 默认给的是 Maven，原因很简单：它在企业级应用里的市场占有率最高，生态最成熟，绝大多数开源示例和教程都以 Maven 作为示例，出现问题也最容易搜到解决方案。
Gradle 的构建速度更快、增量构建体验更好，而且build.gradle 用 Groovy 或 Kotlin DSL 来描述，比 XML 更简洁。但 Gradle 的学习曲线比 Maven 陡峭，同样是解决一个依赖冲突，你在 Maven 下有 dependency:tree 插件可以排查，在 Gradle 下得熟悉 dependencyInsight 任务和各种配置段语义，新手学起来容易一头雾水。
我的建议很直白：除非团队里已经有明确的 Gradle 技术积累，或者项目要到 Android 端做统一构建，否则新项目一律用 Maven。Spring Boot 3.x 对 Maven 的支持没有任何短板，spring-boot-maven-plugin 提供了完善的打包、启动、监控能力。把纠结构建工具的时间省下来，多写两个接口它不香吗。
3.2 语言和运行版本怎么选
语言方面，Spring 官方支持 Java、Kotlin、Groovy 三种。如果你没有特殊偏好，直接 Java 就好。Kotlin 虽然得到 Spring 官方一视同仁的支持，但团队招人、代码库积累、第三方示例丰富度都不如 Java。Groovy 在 Spring Boot 里更像是特定场景下的辅助脚本语言，不适合作为主项目语言。
Java 版本这块值得多说两句。Spring Boot 3.x 要求的最低版本是 Java 17，但 17 并不是唯一选择。到目前这个时间点，JDK 21 作为长期支持版本已经发布超过一年，各大云平台和中间件对新版本 JDK 的兼容性也趋于稳定。如果你完全从零开始、没有历史束缚，我建议直接选 Java 21。这不仅仅是版本数字越新越好，而是 Spring Boot 3.x 里虚拟线程（Virtual Threads）等特性需要 JDK 21 才能完整启用。如果你本机安装的是 Java 21，IDEA 里却没有这个选项，多半是项目 SDK 没设置对，去项目结构里把 SDK 切到 21 就行。
但要注意一个点：代码库的 Java 版本标识和项目实际运行用的 JDK 是两个层面。pom.xml 里的 java.version 定义了编译器源码级别，而你 IDEA 的 Project SDK 定义了实际执行环境，两者不一致时经常出现“代码在别人机器能跑，在你机器报 UnsupportedClassVersionError”的问题，这一点在下面的坑位章节会详细展开。
3.3 项目元数据关系要理顺
Group、Artifact、Name、Package name 这四个字段看起来平平无奇，但很多新手会把它们填得乱七八糟。
Group 对应 Maven 坐标里的 groupId，Java 包名通常也以它开头。公司项目基本用公司域名反写，比如 com.gitee.zzq、com.example。个人项目可以用 GitHub 用户名反写，比如 io.github.username。Artifact 对应 artifactId，是项目名，最终生成的 jar 包名称会带上它，比如 demo-0.0.1-SNAPSHOT.jar。
Name 是项目的外部名称，默认会跟 Artifact 一致，一般不用动。Package name 决定了 Java 代码的根包名，默认是 {groupId}.{artifactId}，比如 com.example.demo。如果你希望代码根包名更短、更好记，可以在这里改成 com.example 或者 com.company.project 之类。这个字段越早确认越好，因为一旦项目代码铺开，根包名迁移非常痛苦，涉及所有 import 语句和配置扫描路径的修改。
打包方式上，Spring Boot 3.x 官方强烈建议用 JAR。过去用 WAR 是因为需要把应用部署到外置的 Tomcat 等 Servlet 容器里，而现在 Spring Boot 自带内嵌 Tomcat、Jetty、Undertow，一个 java -jar 就能启动整个应用。只有在极特殊的、公司容器托管协议强制要求 WAR 的场景下，才需要选择 WAR。选 WAR 时还要多配置一个 SpringBootServletInitializer 子类，对新手来说没有任何好处。
3.4 依赖的加法原则：宁少勿多
新建项目时，很多人的冲动是“把可能用到的依赖都加上，省得以后再加”。我之前带实习生时看到过最夸张的例子，一个只在本地打印 Hello World 的项目，初始依赖加了 17 个，其中包括 WebFlux、Security、JPA、Redis、Kafka、Actuator 一堆东西。最后项目启动要七八秒，日志里全是自动配置类启动信息，查一个问题要看几百行无关日志。
Spring Boot 的自动配置机制是优点也是坑点：只要 classpath 里有某个客户端库，对应的自动配置就会激活，并可能尝试连接外部服务。比如你加了 Spring Data Redis，项目一启动，Redis 自动配置就会尝试创建连接工厂，假如本地没有 Redis 服务，启动过程虽然不会致命报错，但会产生一堆警告，有时候还会影响后续操作的排查判断。
初学阶段，只加你现在要用的。要做 Web 接口，加 Spring Web；要做数据持久化并连接数据库，再加 Spring Data JPA 和对应数据库驱动；要暴露健康检查、指标供后续监控采集，加 Spring Boot Actuator。其他依赖，等你实际需要的时候再用。这里额外提一句，Actuator 底层配合 Micrometer 这套指标门面库非常强大，如果你想做接口调用量、JVM 内存等监控指标采集，创建项目时勾上 Actuator 后，它会把 Micrometer 核心依赖自动带进来，不需要你手动管理版本。
如果你确认后续要用 Redis Stream 做消息队列消费、用 Firebase 做移动端推送或者对接第三方消息通知这类场景，也不需要在一开始就把这些依赖全塞进去，等业务代码真正做到那一步再补充依赖即可，Spring Boot 的 starter 设计使得后期加依赖的成本其实很低，一个依赖 + 几行配置就能搞定，真正的成本在业务代码上。
3.5 我每次生成前必做的“三看一眼”
久而久之，我形成了自己的检查习惯，每次点生成之前，都会花十秒钟扫一眼这四个地方：
- 构建工具确认是 Maven，Group/Artifact 拼写正确，没有奇奇怪怪的大小写和特殊字符。
- Spring Boot 版本选的是当前最新的稳定版，而不是带有 SNAPSHOT、M1、RC1 这类后缀的版本。快照版和里程碑版本适合尝鲜，不适合用在要长期维护的项目里——一旦后续版本迭代，依赖迁移的麻烦概率明显更高。
- Java 版本和本机实际 JDK 一致，避免后续反复切换。
dependencies里只保留当前阶段需要用到的几个 starter。
这套检查流程看起来很短，但它帮我避免了很多不必要的返工。尤其是版本后缀这一点，我看过太多人图新鲜选了快照版，build 的时候第一阶段没问题，过了两周再 build 却拉到了一个有 bug 的快照包，排查半天最后才发现是版本的问题。
4. 生成的项目骨架拆解：不搞清楚就写代码等于盲开
4.1 目录结构讲了什么
我以一个不带任何依赖、只选 Spring Web 的 Maven Java 项目为例，解压出来的结构大概是这样：
code复制demo/
├── src/
│ ├── main/
│ │ ├── java/
│ │ │ └── com/example/demo/
│ │ │ └── DemoApplication.java
│ │ └── resources/
│ │ ├── application.properties
│ │ ├── static/
│ │ └── templates/
│ └── test/
│ └── java/
│ └── com/example/demo/
│ └── DemoApplicationTests.java
├── .gitignore
├── HELP.md
├── mvnw
├── mvnw.cmd
└── pom.xml
DemoApplication.java 是主启动类，带 @SpringBootApplication 注解，后面单独说。application.properties 是默认的配置文件，新版也可以用 application.yml，两者表达的信息基本等价，properties 语法更传统，yml 通过缩进展示层级关系更紧凑。我个人的习惯是新建项目后先把配置文件改名为 application.yml，因为配置项一多，YAML 的层级结构比 properties 那条扁平的长行可读性高太多了。
static 目录用来放静态资源，比如 HTML、CSS、JS、图片，默认根路径映射到这里；templates 目录放服务端模板文件，如果你用 Thymeleaf 这类模板引擎，页面文件就放这里；如果用前后端分离开发，这两个目录在绝大多数情况下都是空着的。test 目录下默认有一个 DemoApplicationTests，它的 @SpringBootTest 注解会让测试环境加载完整的 Spring 上下文，所以第一次运行测试时会启动整个应用上下文，耗时通常在几秒到十几秒之间，这不算异常。
mvnw 和 mvnw.cmd 是 Maven Wrapper 脚本。它的作用是让项目固定使用指定版本的 Maven，而不是依赖本机安装的全局 Maven。团队协作时这非常有用，避免你本机用 3.8、同事用 3.9，构建行为出现细微差异。.gitignore 已经把 target 目录、IDE 配置文件都排除了，导入 Git 仓库后不用改。HELP.md 里是 Spring Initializr 给的简单说明，没有保留价值，我一般直接删除。
4.2 pom.xml 的核心设计逻辑
打开 pom.xml，绝大多数 Spring Boot 3.x 项目的结构其实都非常类似：
xml复制<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>3.3.1</version>
<relativePath/>
</parent>
<groupId>com.example</groupId>
<artifactId>demo</artifactId>
<version>0.0.1-SNAPSHOT</version>
<name>demo</name>
<description>demo project for Spring Boot</description>
<properties>
<java.version>17</java.version>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</project>
注意看，spring-boot-starter-web 这个依赖并没有写 <version>。这是 Spring Boot 项目最容易被忽略、却极有设计巧思的地方。根因在 parent 上的 spring-boot-starter-parent，它内部继承了 spring-boot-dependencies，后者是一张官方的 BOM 依赖清单表，把 Spring Boot 3.x 每个版本配套的第三方库版本全部集中管理了。你只要确定了 Spring Boot 版本，所有 starter 和配套库的版本都由这张表兜底，不需要也不应该自己去写版本号。
spring-boot-maven-plugin 是这个项目能够打包成可执行 jar 的关键。它有两个核心 goal：repackage 会在 Maven 打包阶段把普通 jar 改造成可执行的 fat jar，把依赖库、内嵌容器都塞进去；run 可以让你直接在命令行执行 mvn spring-boot:run 启动应用。如果你不清楚它的作用，把插件注释掉再执行 mvn clean package，你会得到一个打不开的普通 jar，这是排查“打包后 java -jar 运行不起来”这类问题的重要方向。
4.3 主启动类：整个应用的开关
DemoApplication.java 内容通常只有十来行：
java复制package com.example.demo;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class DemoApplication {
public static void main(String[] args) {
SpringApplication.run(DemoApplication.class, args);
}
}
@SpringBootApplication 是一个组合注解，它由三部分组成：@SpringBootConfiguration 标记这是一个配置类，@EnableAutoConfiguration 开启自动配置机制，@ComponentScan 默认扫描当前包及其子包下的所有组件。这句话决定了项目代码必须有清晰的包结构意识：你的启动类放在哪个包，Spring 就只扫描那个包及以下的子包。如果你把 controller 包建在启动类的兄弟层级，Spring 根本扫不到它，接口一通访问就是 404。
我见过很多新手出现“启动类跑起来了，但访问接口总是 404”的诡异问题，最后发现是有人为了方便，把启动类挪到了别的目录层级，或者临时新建的 Controller 放在了启动类包路径之外。定位思路其实很直接：检查你的 Controller 类是否在启动类所在包及其子包下面，不在就移进去，或者用 scanBasePackages 显式指定扫描范围，但我不建议一上来就这么做，默认包扫描规则通常最省心。
4.4 自动生成的测试类与配置文件
默认测试类是一个很好的模板：
java复制package com.example.demo;
import org.junit.jupiter.api.Test;
import org.springframework.boot.test.context.SpringBootTest;
@SpringBootTest
class DemoApplicationTests {
@Test
void contextLoads() {
}
}
contextLoads() 这个方法体是空的，它不测任何业务逻辑，只验证 Spring 上下文能否正常加载。别小看这个空测试，它就像体检时的“常规指标”：如果启动类的包路径、自动配置、Bean 装配有问题，这一跑就全部暴露出来。我建议你拿到新项目后，先跑一次这个测试类，绿灯了再开始写业务代码，这样后续出现问题时就多了一个参考系：它证明至少在初始状态下，整个 Spring 容器是干净的。
配置文件 application.properties 初始内容为空，你可以在里面替换端口号、配数据库地址、定制各种 starter 行为。Spring Boot 的主配置文件名既支持 application.properties，也支持同时存在多个 profile 文件比如 application-dev.yml，通过配置 spring.profiles.active 来切换环境，这又是一个很大的话题，后面专文展开更合适。
5. 跑起来：本地验证一个能用的 Spring Boot 3.x 应用
5.1 运行项目的三种姿势
项目生成好之后，运行方式无非三种。
第一种，IDE 里直接右键 DemoApplication 类，选择 Run。这种方式最直观，适合日常开发调试。IDEA 会在控制台输出 Spring Boot 启动日志，你还可以在 Run 面板里配置环境变量和启动参数。
第二种，使用 Maven Wrapper 命令。在项目根目录执行：
bash复制./mvnw spring-boot:run
Windows 环境用 mvnw.cmd spring-boot:run。这个命令的底层会调起 spring-boot-maven-plugin 完成项目编译和启动。好处是不依赖 IDE，一台只装了 JDK 的机器就能把项目拉起来跑，打包上线前的本地预验证经常用这条命令。
第三种，先打可执行 jar 再跑。执行：
bash复制./mvnw clean package
java -jar target/demo-0.0.1-SNAPSHOT.jar
注意 target 目录下打出来可能有多个 jar，你要找的是名字后面带 -SNAPSHOT 的常规包，而不是带 .original 后缀的那个。后者是 Spring Boot 插件在 repackage 之前生成的原始 jar，直接执行会报 no main manifest attribute 的错误。很多新手就在这个细节上卡过。
5.2 从启动日志里识别关键信息
执行启动命令后，观察控制台输出，正常情况下你会看到类似下面的日志模式：
code复制 . ____ _ __ _ _
/\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
\\/ ___)| |_)| | | | | || (_| | ) ) ) )
' |____| .__|_| |_|_| |_\__, | / / / /
=========|_|==============|___/=/_/_/_/
:: Spring Boot :: (v3.3.1)
2025-01-15T10:24:16.302+08:00 INFO 12345 --- [main] com.example.demo.DemoApplication : Starting DemoApplication using Java 17.0.8 with PID 12345
2025-01-15T10:24:18.754+08:00 INFO 12345 --- [main] o.s.b.w.embedded.tomcat.TomcatWebServer : Tomcat initialized with port(s): 8080 (http)
2025-01-15T10:24:18.908+08:00 INFO 12345 --- [main] o.apache.catalina.core.StandardService : Starting service [Tomcat]
2025-01-15T10:24:19.006+08:00 INFO 12345 --- [main] o.s.b.w.embedded.tomcat.TomcatWebServer : Tomcat started on port 8080 (http) with context path ''
2025-01-15T10:24:19.418+08:00 INFO 12345 --- [main] com.example.demo.DemoApplication : Started DemoApplication in 3.2 seconds (process running for 3.5)
我第一次带新人时就反复强调，看到 Tomcat started on port 8080 (http) 这一行才是真正的启动成功信号，而不是前面的 Started DemoApplication 那一行。虽然说这两行通常一前一后出现，但在某些自动配置场景下可能间隔较长，它们代表的意义偏向两个阶段。前者表示 Web 容器已经就绪并且在监听端口了，后者表示整个 Spring 上下文完成初始化。如果你想确认应用是不是真的对外提供服务了，浏览器访问 http://localhost:8080 会返回一个 Spring Boot 默认的错误页面，而没有网络连接失败的提示，这就够了。
5.3 写第一个“活”的接口验证
只启动项目还不够，得有一个真实接口来验证 HTTP 通路。在启动类旁边建一个 controller 子包，然后新建一个 HelloController：
java复制package 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 3.x!";
}
}
这段代码依赖的 @RestController 和 @GetMapping 都来自 spring-boot-starter-web，所以创建项目时只要勾了 Spring Web，就能直接跑。重新启动应用，浏览器访问 http://localhost:8080/hello，看到字符串 Hello Spring Boot 3.x!，说明你从 Initializr 生成到接口开发这条链路已经完全打通了。
从这一步开始，你可以在 controller 包里持续加业务接口、在 service 和 repository 包里补充业务逻辑和数据访问层，Spring Boot 的包扫描机制会自动接管这些类。前提只有一个：它们都必须在 DemoApplication 所在包的子包下面。
6. 实测中经常踩的坑，按我的排查链路给你走一遍
6.1 “端口被占用”报错：最频繁的启动失败原因
第一个非常常见的启动失败场景：照常点 Run，控制台刷了一堆日志后，弹出一串红色日志，最核心的提示是：
code复制Description:
Web server failed to start. Port 8080 was already in use.
Action:
Identify and stop the process that's listening on port 8080 or configure this application to listen on another port.
如果同时开着多个 Spring Boot 项目就会出现这个问题，默认端口 8080 被占用。排查链路分三步：先用命令找出占用进程，再决定是杀掉进程还是给应用换端口。Mac/Linux 下用 lsof -i :8080，Windows 下用 netstat -ano | findstr 8080 拿到 PID，再通过 kill 或 taskkill 结束占用进程即可。
如果不想动原进程，更优雅的方案是给新项目改端口。在 application.properties 里加一行：
properties复制server.port=8081
或者改成 YAML 形式加在 application.yml：
yaml复制server:
port: 8081
别小看这个问题，我见过不少人在团队协作时共用的开发数据库端口被服务进程占了，排查了很久才发现是某次启动残留的 Spring Boot 进程没有彻底退出，导致新项目启不来。处理办法是不只关 IDEA 的运行窗口，而是确认操作系统层面没有遗留的 Java 进程再做下一次启动。
6.2 本地 JDK 版本和项目版本对不上
另一种频繁出问题的场景是电脑上安装了多个 JDK，比如既有 JDK 8、又有 JDK 17，项目里 pom.xml 写的 java.version 是 17，但 IDEA 的 Project SDK 还指着 8。启动时报错类型通常看起来很像：
code复制java: error: invalid source release: 8
或者编译干脆问 cannot find symbol: class SpringBootApplication，因为依赖在 Java 8 环境下某些类路径处理方式不同。我的处理顺序是先看 pom.xml 里的 <java.version> 项目用的是几，然后到 File -> Project Structure -> Project 命令里把 SDK 切到对应版本，再到 Modules 设置里确认 Language level 与项目版本一致。最后到 Settings -> Maven -> Importing 里把 JDK for importer 也对齐。
如果你用命令行直接 mvn spring-boot:run，还需要确认 JAVA_HOME 环境变量指向的是正确的 JDK。Windows 下有时候系统变量和用户变量存在两套配置，命令行里 java -version 显示 17，但某次运行还是用老的 8，此时要在命令里显式执行 where java 查看实际命中的路径，逐一纠偏。
6.3 Maven 依赖下载慢、莫名卡住
用 Initializr 生成的项目，首次 build 需要拉取大量依赖，如果你的 Maven 还没配置国内镜像源，下载速度可能慢到让人怀疑人生，甚至卡在某个依赖上迟迟不动。
问题根源是 Maven 默认中央仓库在国外，国内网络环境直接访问经常很不稳定。解决方案是在 ~/.m2/settings.xml 里配置 mirrors。常见镜像源有很多稳定可用的，这里贴一个通用配置模式：
xml复制<mirror>
<id>aliyun</id>
<mirrorOf>central</mirrorOf>
<name>Aliyun Maven Mirror</name>
<url>https://maven.aliyun.com/repository/central</url>
</mirror>
配置了镜像之后，后续下载速度会明显提升。如果修改 settings.xml 之前已经卡住的依赖下载，最好把本地仓库里对应的 .lastUpdated 后缀文件清掉再重新拉取，因为 Maven 对下载失败的工件会有缓存，有时候不去清理就会一直报错。
6.4 关于版本和依赖的提醒
在技术社区里，每天都会有新的 Spring Boot 版本发布信息。我的经验是：学习教程和写业务代码，最好锁定一个已经发布了至少两三个补丁版的稳定版本，比如 3.3.x 或 3.4.x；不要一看到 SNAPSHOT、RC 版就急着去更新项目。Spring Boot 小版本之间的升级通常成本较低，大版本的主版本号更换才需要谨慎评估。
还有一点，如果初学阶段报错看不懂，别急着去网上复制一堆不相关的配置。先用完整报错日志里的关键词去搜，搜的时候看 publish 时间不要太久远的，而且优先参考 Spring 官方文档和 GitHub issue。Spring Boot 文档的 “Upgrading From an Earlier Version” 章节基本梳理了每个大版本升级需要改动的地方，把它作为标准参考，比你自己瞎猜要高效得多。
创建项目是整个开发流程里最基础、也最容易忽略风险的一步。用 Initializr 生成一个干净的骨架看似简单，但它为你挡住了很多版本兼容、依赖冲突和结构混乱问题。按我上面讲的配置思路选好依赖、理解目录结构和 pom 设计逻辑、先跑通测试类再写业务代码，后续的开发就会顺畅不少。踩过几次坑之后你会发现，真正省时间的不是跳过这些步骤，而是把每一步的底层逻辑都弄通了，以后不管版本怎么升级，你都能第一时间找到自己的方向。