Spring Boot 2.0.2官方参考指南是一份非常全面的技术文档，但对新手来说，直接阅读英文原版很容易被里面庞杂的配置项和自动装配说明带偏。本文把官方指南中最值得先掌握的部分抽出来，用中文重新组织，帮助你在最短时间内理解起步依赖、自动配置、配置文件加载顺序等核心知识，同时把常见问题和注意事项一并讲清楚。
一、从零搭建一个可运行的Spring Boot应用
官方指南最推荐的初始化方式是访问 start.spring.io 生成项目骨架。选择 Maven 或 Gradle 构建工具，再勾选 Web 依赖，下载后导入 IDE 即可。以 Maven 为例，生成的项目中 pom.xml 会包含一个 parent 节点，这个 parent 就是 Spring Boot 的版本管理中心。你需要重点关注的是 <parent> 中的版本号，2.0.2.RELEASE 表示当前项目继承了 Spring Boot 2.0.2 的依赖管理策略，后续引入 starter 时通常不需要再单独写版本号。
<?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>2.0.2.RELEASE</version>
</parent>
<groupId>com.example</groupId>
<artifactId>demo</artifactId>
<version>0.0.1-SNAPSHOT</version>
<properties>
<java.version>1.8</java.version>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
</dependencies>
</project>
写一个主启动类就能让服务跑起来。官方文档中反复强调 @SpringBootApplication 是一个组合注解，它整合了 @SpringBootConfiguration、@EnableAutoConfiguration 和 @ComponentScan 三个注解的能力。其中 @ComponentScan 会扫描主类所在包及其子包下的所有组件，因此主类的位置很关键。如果把它放在一个太深的包下，可能导致某些公共模块没有被扫描到，这是新手最容易忽略的细节。
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);
}
}
启动成功后，浏览器访问 127.0.0.1:8080 默认会返回一个错误页面，这是因为还没有定义任何控制器。你可以创建一个简单的 RestController 来验证整个链路。这一阶段不需要额外写 XML 配置，也不需要部署到外部 Tomcat，因为 starter-web 中已经内嵌了 Tomcat 容器，这正是 Spring Boot 官方指南反复说明的“约定优于配置”理念。
二、自动配置的运行逻辑与配置文件优先级
自动配置是 Spring Boot 最核心的机制。启动时，@EnableAutoConfiguration 会触发 SpringFactoriesLoader 去读取 META-INF/spring.factories 文件中列出的自动配置类。这些配置类普遍使用了条件注解，例如 @ConditionalOnClass、@ConditionalOnMissingBean、@ConditionalOnProperty 等。只有当 classpath 下存在相关依赖、容器中没有同类 Bean、或者指定属性满足条件时，对应的自动配置才会生效。这也是为什么只引入一个 starter-web 就能自动完成 MVC 配置，而不需要手动注册 DispatcherServlet。
但自动配置不是万能的。一旦你定义了自己的 DataSource Bean，Spring Boot 就不会再自动创建默认的 DataSource。理解这个“退让”原则非常关键，它可以帮助你判断某个 Bean 到底是框架自动装配的，还是你自己注册的。官方参考指南中有专门的章节描述这个替换规则，阅读时可以重点关注“条件注解”相关部分。
配置文件方面，Spring Boot 2.0.2 支持 properties 和 yml 两种格式，默认位置是 src/main/resources 下的 application.properties 或 application.yml。加载顺序遵循从低到高的优先级：jar 包内部的配置文件低于项目外部的配置文件，外部 application.properties 又低于命令行参数。官方文档给出的顺序是：命令行参数、Java 系统属性、操作系统环境变量、当前目录下的配置文件、classpath 下的配置文件。这也解释了为什么有时你在 IDE 里改了端口却不生效，可能是因为命令行或环境变量中已经存在更高优先级的配置。
server.port=8081 spring.datasource.url=jdbc:mysql://localhost:3306/test?useSSL=false spring.datasource.username=root spring.datasource.password=123456
如果你想临时改端口，最可靠的方式是启动时加参数：java -jar app.jar --server.port=9090。这种方式优先级很高，会覆盖文件中的配置。对于 yml 格式，建议保持缩进一致，因为 yml 对空格敏感，层级写错会导致属性无法绑定，但很多编辑器不会直接报错，排查起来比较费时间。
三、新手最容易踩到的五个坑及排查思路
第一个坑是依赖版本不一致。很多初学者在 pom.xml 中混用不同版本的 starter，导致类找不到或方法不兼容。原则上所有 Spring Boot 相关 starter 都应该继承同一个 parent 版本，避免手动指定与 parent 不一致的小版本。如果必须单独指定某个 starter 的版本，务必确认它与当前 Spring Boot 基础版本兼容。
第二个坑是静态资源路径变化。在 2.0.2 版本中，默认静态资源目录是 classpath:/static、classpath:/public、classpath:/resources 和 classpath:/META-INF/resources。如果你把页面放在 src/main/webapp 下，默认是访问不到的。若使用了自定义的 WebMvcConfigurer，还要注意如果重写了 addResourceHandlers 方法，原来的默认路径可能会失效，需要手动重新指定。
第三个坑是数据源自动配置误触发。很多新手在引入 spring-boot-starter-data-jpa 或 mybatis-spring-boot-starter 后，即使没有配置数据源，启动时也会报错，因为自动配置检测到 classpath 下有数据库相关类，就会尝试创建 DataSource。解决办法是在启动类上排除自动配置，或者在配置文件中显式禁用，例如 spring.autoconfigure.exclude=org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration。
- 第四个坑：打包成 fat jar 后读取不到资源文件。要注意 classpath 前缀，使用
ClassPathResource读取文件时不要写绝对磁盘路径。 - 第五个坑：多环境配置切换不生效。2.0.2 中可以通过
spring.profiles.active指定激活的环境，但该属性必须写在主配置文件中，或者通过命令行传入，写在application-dev.yml里是无效的。
排查这类问题时，建议先确认实际生效的配置来源。可以开启 debug 模式，在启动时加上 --debug 参数，Spring Boot 会在控制台输出自动配置报告，明确列出哪些自动配置类匹配成功，哪些被跳过。这份报告比盲目猜测要高效得多，官方指南中也把它作为诊断自动配置问题的首选工具。
四、用官方参考指南辅助长期学习
官方参考指南的结构并不适合从头到尾通读，更适合按需查阅。建议先把“Developing Your First Spring Boot Application”这一章完整走一遍，然后重点阅读“Core Features”中的配置文件、外部化配置和 Profiles 部分。遇到具体模块问题时，再去查阅对应的 starter 章节，比如数据访问、消息队列或缓存。这样阅读负担会小很多，也能快速定位到有效信息。
另一个值得关注的点是官方指南中大量出现的“How-to”小节。这些小节以问答形式给出具体场景的配置片段，非常适合新手现学现用。例如如何修改内嵌 Tomcat 的端口、如何配置 HTTPS、如何自定义错误页面等，都能在其中找到简洁答案。把这些片段和本文提到的基础原理对照起来看，理解会更加扎实。
最后要说明的是，2.0.2 版本已经比较老旧，如果你所在团队技术栈允许，建议逐步升级到更高的 2.x 或 3.x 版本。但很多配置思想和排查方法在 2.x 系列中是相通的，把这一版官方指南吃透，再去看新版本的迁移说明会轻松很多。学习 Spring Boot 的关键不是记配置，而是理解自动配置背后的条件判断和 Bean 替换机制，这套思想在后续版本中依然适用。
Spring Boot官方参考指南新手入门修改时间：2026-10-03 23:03:23