第一次用Spring Boot的时候，我还在用传统SSM写项目，光配置XML就写了半天，数据源、事务、扫描包、视图解析器，随便一处忘了配就是各种奇奇怪怪的报错。后来转Spring Boot，最大的感受就是“原来项目还能这么搭”：不用部署独立容器，不用写一堆配置文件，一个main方法点下去，项目就自己跑起来了。这篇内容就是写给完全零基础的朋友，带你从环境准备开始，亲手创建一个Spring Boot项目，理解配置文件的用法，最后把第一个接口跑起来。整个过程不追求大而全，只求每一步都踩实，看完你就能在自己的电脑上搭出一个可运行的最小项目。
1. 为什么从Spring Boot开始？——先搞清楚它解决了什么问题
1.1 Spring Boot到底是个啥
Spring Boot不是一个新的编程语言，也不是一套独立的框架，它本质上是Spring生态的一层“自动装配外壳”。传统Spring项目需要你手动组合各种依赖、配置各种Bean、处理各种XML或注解，新手经常卡在“配置半天还不知道错在哪”。Spring Boot做的核心事情就两件：一是自动配置，二是内嵌容器。自动配置会根据你引入的依赖自动帮你装配好常见的组件，比如你引入了Web相关的依赖，它就会自动配置好Spring MVC和Tomcat；你引入了MyBatis依赖，它会自动配置数据源和SqlSessionFactory。你不用再写那一大堆重复的配置类。
内嵌容器解决的是部署问题。原来的Java Web项目打出来的war包要放到Tomcat的webapps目录下，然后启动外部Tomcat才能运行。Spring Boot支持直接把Tomcat打成依赖打包进应用里，你运行一个main方法，Tomcat就在应用内部启动了一个端口监听，项目的启动和部署变成了“一个Java进程”的操作，这让开发调试和项目迁移都变得特别方便。
第二个好处是“起步依赖”机制。你不需要自己一个个找版本号，Spring Boot把常用功能整理成了若干起步依赖，比如spring-boot-starter-web就包含了Spring MVC、Jackson、内嵌Tomcat这些Web开发必需的东西。你只需要引一个依赖，版本由父工程统一管理，减少了大量版本冲突问题。这一点对新手极其友好，你不用去看Spring核心和Spring MVC分别该用哪个版本，Boot已经帮你把版本兼容关系都锁定了。
1.2 适用场景与前置知识
Spring Boot适合的场景很广：微服务、独立API服务、中小型业务系统、快速原型、内部工具后台等等都能用。它并不只属于“微服务架构”这个范畴，很多单体项目用Boot来做开发同样非常顺手。因为它最大化了开发效率，让开发者把精力集中在业务代码上，而不是环境搭建。对于刚入门Java Web的同学来说，Spring Boot其实是一个比传统SSM更合适的起点，因为你还不用理解那么多底层原理的时候，就能先跑出东西来，这种正反馈很重要。
不过我也要说句实话：Spring Boot虽然简化了配置，但它并没有降低对Java基础的要求。建议你在学之前至少掌握：Java语法（类、接口、集合、泛型、Lambda）、Maven基本概念（依赖坐标、仓库、生命周期）、HTTP的基本概念（请求、响应、GET/POST）以及一些Spring的基础注解知识，比如@Controller、@Service是什么意思。如果你Java基础还不牢，建议先补一补Java SE内容，否则可能连报错日志都看不懂，排错会比较吃力。当然了，这不代表你要把所有Java知识学完才能碰Boot，边学边补也是完全可以的，我就是这么走过来的。
2. 环境准备：搭建之前必须备好的工具箱
2.1 JDK版本选择与安装验证
Spring Boot 2.x和3.x对JDK版本的要求不一样。如果你现在还比较迷茫，我的建议是优先选Spring Boot 2.7.x，搭配JDK 8或JDK 11，因为网上大部分教程、博客、遇到的问题都是基于这个组合，参考资料多，踩坑也少。Spring Boot 3.x要求JDK 17及以上，起步能用，但一些老版本依赖可能出现兼容问题，新人排查起来会很痛苦。不是3.x不好，而是当你还分不清“依赖冲突”和“代码写错”有什么区别时，选一个最稳的环境能让你把注意力放在业务上。
安装JDK之后，务必验证一下。Windows下在命令行里执行java -version，Mac/Linux也一样。看到类似“openjdk version ”或者“java version 1.8.0_xxx”这种输出就说明基础环境没问题。很多同学卡在“找不到或无法加载主类”这种问题，十有八九是JDK没装好或者环境变量没配好。另外要注意，如果你同时装了多个JDK版本，命令行里java -version显示的版本不一定是你IDE里选择的版本，建议统一设置你的开发工具内置的JDK路径，避免两边不一致。
说到环境变量，Windows用户需要配置JAVA_HOME、PATH、CLASSPATH这些，网上教程一搜一大把。我只提醒一个点：新版本的JDK安装包在Windows上安装时，一般会自动写入注册表并配置PATH，但JAVA_HOME可能不会自动配全，建议还是手动确认一下。而Mac用户直接用Homebrew安装OpenJDK相对更干净，也更好卸载。
2.2 Maven的安装与镜像配置
Maven是Java项目的构建工具，负责依赖下载、编译、打包。Spring Boot项目的核心配置文件pom.xml就是Maven的配置模型，所以Maven是绕不开的。安装方式很简单：去官网下载二进制压缩包，解压，然后配置M2_HOME和PATH，在命令行输入mvn -v能输出版本号即可。
但装了Maven并不代表就完事了，国内网络环境下最现实的坑是依赖下载非常慢。默认的中央仓库在国外，你下载spring-boot-starter-parent那几十MB依赖时，可能体验极差。我建议你拿到Maven之后第一件事就配置阿里云等国内镜像源。具体方法是找到Maven安装目录下的conf/settings.xml，在<mirrors>节点里添加一个mirror配置，内容大致如下：
<mirror> <id>aliyunmaven</id> <name>Aliyun Maven Mirror</name> <url>https://maven.aliyun.com/repository/public</url> <mirrorOf>central</mirrorOf> </mirror>这里的mirrorOf用的是central，意思是只对中央仓库生效，不会影响其他私有仓库。配好之后，你的依赖下载速度会有质的提升。另外还有一个细节：如果你在IDE里配置了Maven，但发现下载还是很慢，记得检查IDE里设置的settings.xml是不是真的指向了你修改的这个文件。很多人是全局改了文件，但IDE默认用了自己内置的Maven配置，导致修改完全不生效。
2.3 开发工具的选型
开发工具个人推荐IDEA，社区版对Spring Boot的支持已经足够用，可以直接导入Maven项目，自动识别Spring Boot的main方法。如果你用的是Eclipse或VS Code，也可以跑起来，但体验和维护成本会略高一些。为什么首推IDEA？因为它的Spring插件给你做了太多隐形服务：依赖自动提示、配置项提示、一键运行按钮、断点调试、内置终端。这些对于新手来说能节省大量时间。
这里我想给新手一个额外建议：不要过度依赖IDE的自动补全，基础阶段要时不时打开源码看看。尤其是当你看到某个类或注解不明白时，按住Ctrl键点击去，顺着源码读几行，很多疑团会瞬间解开。我第一次看spring-boot-autoconfigure包里的源码时确实有些吃力，但那些自动配置类的命名和逻辑都很直观，读几个就能理解Spring Boot“自动配置”的本质。这个习惯如果从入门阶段就养成，后面学习会非常顺畅。
3. 创建项目：从Spring Initializr到本地目录结构
3.1 用初始化服务生成项目骨架
快速创建Spring Boot项目最常用的方式有两种：一种是用IDE自带的Spring Initializr，另一种是访问Spring官方初始化网站生成压缩包再导入IDE。推荐使用IDE自带的方式，因为你生成之后直接就是可导入的工程，省去解压和导入的步骤。
以IDEA为例，新建项目时选择“Spring Initializr”，然后填写项目信息：Group一般写公司域名倒序，比如com.example；Artifact写项目名，比如demo；Type选Maven；Java版本要和你的JDK对应。在依赖选择界面，先勾选“Spring Web”这一个起步依赖就够了，其他数据库、Redis、消息中间件之类的一概不用勾，后边用到再加。这样生成出来的项目是最干净的，排查问题也更容易。
如果你在网站上下载压缩包，解压后是一个标准Maven工程目录，可以直接用IDE打开，选择导入Maven项目。不管用哪种方式，最终生成的pom.xml里都会带spring-boot-starter-parent父工程和spring-boot-starter-web依赖，以及一个带有main方法的启动类。
3.2 认识生成出来的项目结构
项目生成之后，你会看到一个固定的目录骨架，src/main/java和src/main/resources。前者存放Java源代码，后者存放配置文件、静态资源、模板文件。Maven约定优于配置，Spring Boot也沿用了这套约定。只要你的目录结构符合约定，框架就能自动找到你要放的东西，这也是新手容易忽略但必须接受的一个规则。
在java目录下，还会有一个带Application后缀的启动类，比如说DemoApplication，这就是整个应用的入口。它虽然看起来只是一个普通的类，但上面有两个关键注解：@SpringBootApplication。这个注解是一个组合注解，包含了@SpringBootConfiguration、@EnableAutoConfiguration和@ComponentScan。其中@EnableAutoConfiguration就是前面提到的自动配置开关，@ComponentScan负责自动扫描当前包及其子包中的Spring组件。所以你的Controller、Service这些类要放在启动类所在包的下级包中，否则扫描不到。
resources目录下会有一个application.properties文件，目前是空的，但它已经可以被Spring Boot加载。如果你以后写配置，就写在这个文件里；如果你用YAML格式，也可以改成application.yml。这两个文件后面会细说。还有一个static和templates目录，目前可能不存在或为空，它们分别用来放前端静态资源和服务端模板页，初学者可以暂时不管。
3.3 关键配置文件pom.xml解读
pom.xml是Maven项目的核心，我们看一下最初生成的pom内容的关键部分：
<parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>2.7.18</version> <relativePath/> </parent>这一段就是父工程，它的作用很强大。父工程里给你预定义了大量常用依赖的版本号，以及Maven插件的默认配置。你在子工程里引入依赖时，通常不需要写版本号，Maven会去父工程找默认版本。这样就解决了“依赖版本不好选”的问题。
接着是依赖部分：
<dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> </dependencies>spring-boot-starter-web里面整合了Spring MVC、内嵌Tomcat、Jackson JSON处理库等。你会发现你只写了一个依赖，Web环境就齐了。这也在提醒你一个思维：以后要加什么功能，优先找对应的starter，而不是搜索一个个零散的jar包自己拼。
pom.xml里还有一个build节点，里面配置了spring-boot-maven-plugin，这个插件负责把项目打成可执行的jar包，并且能把Spring Boot应用打包成一个包含所有依赖的独立可运行包。没有这个插件的话，你打出的jar包就是一个普通jar，不带依赖，也没法直接运行。打包时记得通过这个插件来打。
4. 第一批配置：application.properties还是YAML
4.1 配置文件的优先级与书写风格
Spring Boot支持两种格式：application.properties和application.yml，两者在默认情况下同时存在时，properties文件优先级更高。所谓优先级高，就是如果同一个配置项在两个文件里都出现了，properties里的值生效。这个规则我在实际中踩过一次：项目里两个文件都有，我在yml里改了服务端口但怎么都不生效，一查才发现properties里的旧值还在，把它注释掉就好。
格式上，properties是老派写法，用等号表示键值对；YAML用缩进表示层级关系，更清爽。比如配置Tomcat端口和上下文路径，properties写法是：
server.port=8081 server.servlet.context-path=/demoYAML写法是：
server: port: 8081 servlet: context-path: /demo两种都能用，我的习惯是新项目统一用yml，层级多的时候阅读效率高。但要注意YAML对缩进非常敏感，严禁使用Tab缩进，必须用空格，而且同一层缩进必须一致。很多新手把复制来的YAML粘进去后发现项目起不来，多半是缩进出了问题。你可以让IDE帮你格式化，能自动修正一部分。
4.2 最常用的几个内置配置项
刚起步的时候不需要背太多配置项，但下面这几个可以先认识一下，它们会频繁出现在你的开发过程中。
server.port：修改应用启动端口，默认是8080，如果被占用就改成8081或者其他可用端口。server.servlet.context-path：加上应用的访问前缀，比如配置成/demo之后，接口访问路径就变成http://localhost:8081/demo/hello。spring.application.name：给应用起个名字，微服务环境下尤其重要，本地单机跑的时候看不出多少作用，但养成配置习惯是好的。logging.level.root：修改日志级别，比如配置成info用来控制控制台输出量。
想知道更多配置项时，不要靠记忆，直接在IDE里输入配置键名，IDEA会自动提示，并且会显示注释说明。如果你使用Spring Boot的配置处理器（spring-boot-configuration-processor）它还可以帮你生成配置元数据，但入门阶段不需要搞那么复杂。
4.3 自定义配置的读取方式
除了框架内置的配置，你也可以在配置文件里写自己的业务参数，比如一个默认的页码大小，或者某个第三方服务的地址。读取方式很简单，用@Value注解取出来：
@Component public class MyConfig { @Value("${app.page-size:10}") private int pageSize; }这个含义是读取配置项app.page-size，如果找不到就使用默认值10。这里有个小坑：自定义配置项建议用统一前缀，比如app.xxx，避免和Spring Boot已有的配置项冲突。自定义配置值都注入到一个类里，这种写法更好维护，但入门阶段先用@Value理解读取机制就足够了。
还有一点要留意：修改配置文件后必须重启应用才能生效，除非你配置了自动重启。当我们还在用本地开发模式时，Spring Boot不会像浏览器刷新页面那样自动加载新配置。如果你要频繁改配置，建议先把热部署给做上，后面章节再展开。
5. 初步运行：让第一个接口跑起来
5.1 写一个最简单的Controller
运行之前，先写一个可以被访问的接口。这里要建一个controller包，然后创建一个类：
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!"; } }关键就两个注解：@RestController表示这个类是一个处理HTTP请求的控制器，并且返回值会直接写入HTTP响应体。它等价于@Controller加@ResponseBody的组合。@GetMapping("/hello")表示映射一个GET请求，路径是/hello。所以你访问http://localhost:8080/hello时，就会收到一串文本“Hello Spring Boot!”。
有人会问：这里为什么没有配置Spring MVC的视图解析器？为什么不写web.xml？答案就是Spring Boot自动配置在起作用：你引入了web starter，它就自动配置了DispatcherServlet和默认的路径映射。这些在传统SSM里都是手工活儿，在Boot里都被自动化了。
5.2 三种运行方式对比
第一种方式最无感：在启动类里找到main方法，旁边会有绿色三角形运行按钮，点它就能启动。日志输出到控制台，看到“Started DemoApplication in x.xxx seconds”说明启动成功了。这种方式适合日常开发调试。
第二种方式是命令行使用Maven插件运行。在项目根目录执行：
mvn spring-boot:run它和IDE里点运行本质一样，适合在你没有开IDE或者想验证远程环境的时候用。它的前提是Maven配置好并能正常下载依赖。
第三种方式是打包后运行。执行：
mvn clean package之后在target目录下会生成一个xxx.jar，通过：
java -jar target/xxx.jar就可以启动应用。这就是Spring Boot最吸引人的地方——一个jar包就是一个完整应用，带上依赖和容器，不需要额外安装Tomcat。在生产环境部署时也基本是这种方式。当你确认本地代码没问题，最后大多要走这一步。为了验证linux环境下也可以跑，我在云服务器上也试过很多次，确实只依赖JDK，非常省事。
5.3 验证接口的细节
启动成功后，打开浏览器访问http://localhost:8080/hello，你应该能看到纯文本输出。如果你配置了context-path，记得要把前缀带上。访问不了时不要慌，按下面顺序排查：
- 看控制台日志有没有出现“Started ...”字样。如果卡在“Tomcat started on port(s): 8080”之前，说明项目还没启动完，多等一会。
- 看端口号。日志会明确告诉你Tomcat启动在哪个端口，别自己猜。
- 用命令行工具测试更可靠。浏览器可能会缓存，用curl测试是准的：
curl http://localhost:8080/hello另外建议你尝试访问一个不存在的路径，比如/abc，你会看到Spring Boot的错误页面信息。这说明HTTP层已经正常工作了，只是路径不对。能区分“服务起来了”和“接口不存在”是入行必须的基本功。
6. 常见问题与排查技巧
6.1 端口被占用怎么办
这是新手百分百会遇到的问题。错误提示通常会包含“Port 8080 was already in use”，原因就是有另一个进程占用了8080。解决办法有两种：一是换端口，在配置文件里把server.port改成8081；二是找到占用进程并结束它。Windows下可以通过：
netstat -ano | findstr 8080查看PID，再通过：
taskkill /PID 进程号 /F结束进程。Mac/Linux下可以用lsof -i:8080找到进程PID，再用kill -9 进程号强杀。如果你是用IDE启动的，经常出现旧的Spring Boot进程还没完全退出，新启动又起不来的情况，这时候直接去任务管理器或活动监视器把Java进程结束掉更干脆。
6.2 依赖下载慢或失败
Maven项目第一次构建时需要下载大量依赖，如果没配镜像，你可能会看到进度条长时间不动，最后报错。这类错误信息五花八门，比如“Could not transfer artifact ...”，“Connection timed out”，“PKIX path building failed”等等。绝大多数都是网络问题。
处理顺序是：先确认settings.xml里mirror配置是否正确；再确认IDE里使用的Maven路径；然后删除本地的~/.m2/repository中对应未下载完全的目录，重新刷新依赖。有时候依赖包只下载了一半就被中断，会产生一个.lastUpdated文件，Maven默认会认为这个依赖已经尝试过而拒绝重新下载，很多人不知道这一点，一直刷新也没用。正确做法是把对应目录清空，再重新reimport。如果你用了IDE的“重新加载所有Maven项目”还是不行，就去仓库目录把失败缓存删掉。
6.3 改了配置不生效
有两个容易忽略的场景。第一个是配置文件名拼错了，比如写成了application.yml和application.properties同时存在，或者把文件放到了项目其他目录而没放resources根目录。Spring Boot只会加载默认文件名和默认路径下的配置文件，路径不对自然不生效。第二个是配置项名称写错了，比如把server.port写成了server.portt，启动时Spring Boot会直接忽略未知配置，不报错。这一点坑很大，所以建议在IDE里打开配置提示功能，如果输入键名没有高亮提示，大概率是拼错了。
还有一个冷门但实际遇到过的情况：在类里用@Value读配置，但@Value的写法里漏了${...}符号，导致注入的是字符串本身而不是配置值。这种问题不仔细看真的很难发现，建议写完之后在控制台打印一下变量值确认。
6.4 热部署配置与使用
每次改代码就重启应用，确实很浪费时间。Spring Boot提供了spring-boot-devtools实现开发期的自动重启。引入方式是在pom.xml里加：
<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-devtools</artifactId> <optional>true</optional> </dependency>加完之后，IDEA里还需要开启自动编译选项：Build Project automatically，并且在高级设置里允许IDEA在应用运行时的自动编译。这样你改完代码，保存一下，应用会自动重启。注意它不是像前端热更新那样局部替换，而是重启整个应用，只是比手动重启快很多。
devtools还有一种“远程重启”功能，但不建议新手用，维护成本高且存在安全风险。本地开发用它提升效率就够了。生产环境不要带devtools，因为optional=true已经让它不会被传递到其他模块，打包也会默认排除。
7. 收尾：下一步往哪走
到这里你已经亲手完成了Spring Boot项目的搭建、配置和首个接口的运行。这看似简单，但其实你已经摸清了Spring Boot最核心的一种开发节奏：建项目、看结构、加依赖、写配置、写接口、跑起来、看日志。后面所有更复杂的应用，不管加数据库、加缓存、加消息队列，都是在当前这个基础上蔓延开来的。
我个人学到这里时的体会是：一定要亲手把这个流程重复几遍，尤其是打包和命令行运行那一步，不要一直依赖IDE按钮。等你习惯了一个jar包跑起来的这种部署方式，再回去看“为什么系统部署这么方便”，会比直接背概念理解深刻得多。
下一步建议你尝试两件事：第一，把这个接口改成返回JSON格式的对象数据，用@RestController配合一个简单的POJO类，看看Spring Boot如何自动把对象序列化成JSON；第二，尝试写一个带请求参数的接口，比如@GetMapping("/hello/{name}")，体会一下路径参数的绑定方式。这两件事都很小，但能把Spring MVC的基础链路打通。等这两件事做完，再考虑引入数据库操作，那时候你才真正进入“业务开发”的门槛。别着急，一步一步来，这条路我已经替你趟过一遍了。
