写了好几年Java我一直觉得Spring Boot最神奇的地方就是那一行SpringApplication.run。不知道你有没有好奇过为什么只写一个SpringBootApplication再执行一个run方法一个能处理请求的Web服务就起来了这背后不是魔法而是一套设计得相当精密的启动流程。搞懂它不只是为了面试更是在线上遇到启动慢、自动配置不生效、端口起不来这类问题时能顺着链路快速定位的思路基础。这篇文章我会从启动入口拆起逐步讲到环境准备、自动配置、内嵌容器和事件机制最后分享一些我自己排查启动故障时积累的经验。适合刚接触 Spring Boot、想从“会用”进阶到“懂原理”的同学也适合工作一两年的后端开发来查漏补缺。1. Spring Boot 启动的宏观链路从 main 方法到服务就绪1.1 启动入口的两段式构造先说结论。Spring Boot 的启动入口是固定的三板斧哪怕项目再复杂最后都会收敛到那一行SpringApplication.run上。很多新手以为这行代码做了“启动一个 Tomcat”这么简单的事实际上它内部被拆成了两段先new SpringApplication(主类.class)再调用这个实例的run(args)。第一段构造过程里有几件关键事值得展开讲。public SpringApplication(ResourceLoader resourceLoader, Class?... primarySources) { this.webApplicationType WebApplicationType.deduceFromClasspath(); this.bootstrapRegistryInitializers new ArrayList( getSpringFactoriesInstances(BootstrapRegistryInitializer.class)); this.initializers new ArrayList( getSpringFactoriesInstances(ApplicationContextInitializer.class)); this.listeners new ArrayList( getSpringFactoriesInstances(ApplicationListener.class)); this.mainApplicationClass deduceMainApplicationClass(); }推断 Web 应用类型。Spring Boot 启动时会扫一遍 classpath看有没有org.springframework.web.servlet.DispatcherServlet、jakarta.servlet.Servlet、org.springframework.web.reactive.DispatcherHandler这些类从而判断当前应用是传统的 Servlet Web 应用还是响应式的 Reactive Web 应用或者根本就是个非 Web 应用。这一步直接决定了后面创建哪种 ApplicationContext。加载三组 SPI。从约定文件里把BootstrapRegistryInitializer、ApplicationContextInitializer、ApplicationListener的实现类全部实例化出来。注意这里用的是getSpringFactoriesInstances本质就是读取 classpath 下所有 jar 里的约定配置再做去重和实例化。这就是为什么你引入某个 Starter 后它的自动配置、监听器天然会被感知到不需要写一行注册代码。推断主启动类。通过当前线程的堆栈找到包含 main 方法的那个类。网上很多教程会说“主类必须包在根包下”其实 Spring Boot 为了兼容非标准布局提供了一套兜底手段直接扫栈。如果你自己写的工具里也调用SpringApplication.run要小心主类推断可能不准确这算是比较少人注意的坑。1.2 run() 方法的核心执行节奏Spring Boot 2.x 的 run 方法核心流程我做了精简把骨架留出来。public ConfigurableApplicationContext run(String... args) { StopWatch stopWatch new StopWatch(); stopWatch.start(); DefaultBootstrapContext bootstrapContext createBootstrapContext(); SpringApplicationRunListeners listeners getRunListeners(args); listeners.starting(bootstrapContext, this.mainApplicationClass); ConfigurableEnvironment environment prepareEnvironment(listeners, bootstrapContext, args); printBanner(environment); ConfigurableApplicationContext context createApplicationContext(environment); // ...异常报告器、上下文加工、刷新、启动后处理省略 refreshContext(context); afterRefresh(context, applicationArguments); stopWatch.stop(); listeners.started(context, timeTakenToStartup); callRunners(context, applicationArguments); listeners.ready(context, timeTakenToReady); return context; }我把这段流程按顺序和阶段总结成一张表方便你对照。阶段关键动作对应事件启动计时创建 StopWatch记录启动总耗时无监听器开始通知所有运行监听器应用开始启动ApplicationStartingEvent环境准备加载默认属性、命令行参数、多 profile 配置ApplicationEnvironmentPreparedEventBanner 打印输出启动 Banner可自定义/关闭无上下文创建按应用类型创建 AnnotationConfigServletWebServerApplicationContext 等ApplicationContextInitializedEvent上下文刷新执行 Bean 定义解析、注册、实例化Tomcat 在此阶段启动ApplicationPreparedEvent、Spring 容器事件启动完成启动计时结束触发启动完成事件ApplicationStartedEventRunner 执行执行 ApplicationRunner / CommandLineRunner无就绪通知应用完全就绪可以接收流量ApplicationReadyEvent注意一个容易误解的地方在 Spring Boot 的启动日志里Started Application in X seconds出现的位置对应 ApplicationStartedEvent但在它之前其实内嵌 Tomcat 已经启动并占用了端口。真正能对外提供服务是等 ApplicationReadyEvent 发出之后。中间差的那点时间通常就是各种 Runner 和PostConstruct的预热逻辑。1.3 三种 ApplicationContext 的创建路径Spring Boot 不像传统 Spring 项目那样要你手动选ClassPathXmlApplicationContext还是AnnotationConfigApplicationContext它根据第一步推断出的 Web 应用类型自动创建。SERVLET 类型创建AnnotationConfigServletWebServerApplicationContext。它会注册默认的DispatcherServlet、过滤器链、内嵌容器管理等相关 Bean。REACTIVE 类型创建AnnotationConfigReactiveWebServerApplicationContext。走 WebFlux 那一套内嵌容器可能是 Netty。NONE 类型创建AnnotationConfigApplicationContext。比如命令行跑批任务、定时任务的应用就不会启动任何 Web 容器。对大部分业务系统来说你永远只会用到第一种。但这个推断机制告诉我们一件事如果你不小心引入了一个 Web 相关依赖而你的应用本来不需要 Web 容器启动时可能会出现Web server failed to start这类莫名其妙的错。排查的思路不是去怀疑配置写错了而是先把应用类型拉回预期。2. 自动配置是怎么“自动”起来的SPI 与条件装配2.1 SpringBootApplication 拆开看启动原理很多人讲不清楚是因为把两个概念混在了一起Spring 容器的启动和 Spring Boot 的自动配置。前者是“把 Bean 装进来”后者是“决定装哪些 Bean”。拆开看就清晰了。SpringBootApplication是一个合成注解它等价于下面三条SpringBootConfiguration本质是Configuration标记这是一个配置类。EnableAutoConfiguration开启自动配置机制这是整个 Spring Boot 的灵魂。ComponentScan扫描当前包及其子包下的Component、Service、Repository、Controller等组件。这里有个经典坑如果把ComponentScan的 basePackage 改成了其他包而且又没包含主类所在的包那么很多本来应该被扫描到的业务 Bean 会静默消失。所以大型项目用SpringBootApplication时要么别乱改扫描路径要么把扫描范围显式放到足够大的公共包上。EnableAutoConfiguration内部通过Import(AutoConfigurationImportSelector.class)引入一个导入选择器这个类会在解析配置阶段被触发返回一组自动配置的类全限定名。接下来要说的加载机制就集中在这个导入选择器上。2.2 自动配置候选的加载来源手动深入AutoConfigurationImportSelector的时候你会看到这些关键方法getCandidateConfigurations()拿到所有自动配置候选类名。getExclusionAutoConfigurations()处理spring.autoconfigure.exclude和EnableAutoConfiguration(exclude...)的排除清单。filter()用一组条件过滤器把不满足条件的配置类从候选列表中剔除。removeDuplicates()去重。sort()按照自动配置类上的AutoConfigureOrder、AutoConfigureBefore、AutoConfigureAfter排序。候选类名从哪里来Spring Boot 2.7 之前是META-INF/spring.factories文件里的org.springframework.boot.autoconfigure.EnableAutoConfiguration配置项2.7 开始引入新的META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports3.x 起彻底抛弃 spring.factories 这条通道。# spring.factories 形式2.7 以前 org.springframework.boot.autoconfigure.EnableAutoConfiguration\ com.example.demo.config.MyAutoConfiguration # AutoConfiguration.imports 形式2.7 com.example.demo.config.MyAutoConfiguration你引入一个第三方 Starter 时它 jar 包里如果带了这个 imports 文件启动时就会被 Spring Boot 读到。这也是为什么你只需要引入依赖不用手动Import配置类的原因。自己写公共模块想做得方便一点也应该按这个形式提供自动配置而不是让使用方手动 import。2.3 条件装配的常见套路加载进来的自动配置类不可能全都生效。比如你的项目没引入 Redis 客户端Redis 自动配置就应该自动放弃。Spring Boot 用一堆Conditional注解来完成这种判断常见的有ConditionalOnClassclasspath 中存在某个类才生效。ConditionalOnMissingBean容器中没有某个 Bean 才生效。ConditionalOnBean容器中存在某个 Bean 才生效。ConditionalOnProperty配置项满足匹配值才生效。ConditionalOnWebApplication应用是 Web 应用才生效。拿RedisAutoConfiguration举例它的类头大致长这样AutoConfiguration ConditionalOnClass(RedisOperations.class) EnableConfigurationProperties(RedisProperties.class) Import({ LettuceConnectionConfiguration.class, JedisConnectionConfiguration.class }) public class RedisAutoConfiguration { Bean ConditionalOnMissingBean(name redisTemplate) public RedisTemplateObject, Object redisTemplate(RedisConnectionFactory factory) throws UnknownHostException { // ... } }第一层ConditionalOnClass(RedisOperations.class)决定了只要 classpath 里没有 Redis 驱动整个配置类直接跳过。第二层对 redisTemplate 这个 Bean 的判断如果业务代码里自己定义了一个名为redisTemplate的 Bean自动配置的默认模板就不再注册这遵循“用户可以覆盖默认实现”的设计思想。这里有个非常容易踩的坑ConditionalOnMissingBean对 Bean 的判断发生在注册阶段而不是解析阶段。如果你的业务 Bean 是靠ComponentScan扫描进来的Spring Boot 会先处理自动配置类再扫描主程序包时ConditionalOnMissingBean有可能误判。要规避它通常是调整自动配置类与扫描的先后顺序或者不用缺失判断专门写一个ConditionalOnProperty来决定是否启用。2.4 用 --debug 拿到专属自动配置报告排查“某个自动配置为什么没生效”的最快方法是启动时加参数或者在application.properties里写debugtrue。启动之后日志里会出现两段关键输出Positive matches命中的自动配置类后面会列出命中的条件注解。Negative matches未命中的自动配置类并且会说明是哪个条件不满足。比如说你怀疑某个ConfigurationProperties没生效看 Negative matches 里会直接提示ConditionalOnProperty的哪一项没匹配上。有些项目日志出于安全考虑关闭了启动信息那就在本地启动时专门开一次--debug看完再关。这个能力在生产排查同类问题时也很有价值但要注意日志量大不要在高峰时段随便开。3. Web 环境的启动细节内嵌容器与监听器机制3.1 内嵌 Tomcat 的启动链路Spring Boot 默认的 Web 容器是 Tomcat但你没有手动写过 Tomcat 配置容器是怎么起来的要追溯到ServletWebServerFactoryAutoConfiguration这个自动配置类。解析ServletWebServerFactoryAutoConfiguration时发现 classpath 里有Tomcat.class于是往容器里注册TomcatServletWebServerFactory。刷新上下文阶段ServletWebServerFactoryAutoConfiguration.BeanPostProcessorsRegistrar会注册一堆后置处理器其中WebServerFactoryCustomizerBeanPostProcessor会把你在配置类里定义的WebServerFactoryCustomizer应用到工厂上端口、压缩、超时等配置都在这时被改写。WebServerStartStopLifecycle或者ServletWebServerApplicationContext.onStartup阶段会调用factory.getWebServer()这个方法内部创建真实的 Tomcat 对象设置 Connector准备 Context最后调用tomcat.start()绑定端口。整个过程最容易被忽略的是Tomcat 在这里实际上是一段“容器生命周期”管理而不是单纯的 Socket 服务启动。Spring MVC 的DispatcherServlet是通过DispatcherServletRegistrationBean注册进 Tomcat 的 Servlet 上下文里的。把这两件事分开理解后遇到“端口起不来”和“请求 404”两类问题时你就能快速定位到底是容器层的问题还是 Servlet 层的问题。3.2 事件广播与监听器启动过程的“导航信号”Spring Boot 启动全程会发出多个事件这些事件统称SpringApplicationEvent。它们走的是SpringApplicationRunListeners而不是 Spring 容器的事件广播器。区别在于前者发生在容器刷新之前、之中、之后的各种阶段后者至少在上下文刷新完成后才会完整介入。我整理了一份事件速查表排查问题时可以直接对照。事件触发时机典型用途ApplicationStartingEvent启动开始环境未构建记录启动日志、设置载入参数ApplicationEnvironmentPreparedEvent环境已准备容器未创建根据环境调整日志级别、过滤配置项ApplicationContextInitializedEvent上下文已创建Bean 未开始加载扩展点注册ApplicationPreparedEvent准备刷新上下文预热数据源、预创建连接池ApplicationStartedEvent上下文已刷新Runner 未执行上报启动状态、执行轻量校验ApplicationReadyEvent全部就绪发心跳、预热缓存、开任务ApplicationFailedEvent启动失败保存故障现场、推送告警举个例子我之前遇到一个场景某个服务要求上线后立刻把注册信息报到配置中心但启动日志显示服务正常配置中心里却迟迟没有数据。后来发现数据上报逻辑写在ApplicationStartedEvent监听里而这个时候 Runner 还没跑完注册中心客户端连接的超时时间偏大导致上报丢失。调整到ApplicationReadyEvent之后问题立刻消失。这就是事件时序对业务代码的直接影响了。3.3 配置加载的顺序与优先级环境准备阶段还有个容易被小看的能力属性来源的合并。Spring Boot 的ConfigurableEnvironment会维护一个属性源列表后加入的覆盖先加入的。默认优先级从高到低大致是这个顺序命令行参数--server.port8090Java 系统属性-Dserver.port8090操作系统环境变量SERVER_PORT8090application-{profile}.yml如 application-prod.ymlapplication.yml/ application.properties默认属性代码里通过setDefaultProperties设置的所以“application.yml 里明明写了端口 8080启动后却是 8090”这种事大概率不是文件写错了而是命令行参数或者环境变量的优先级把配置覆盖了。排查这类问题的方法是写一个临时Environment打印所有属性源或者启动日志里临时打开debug看看EnvironmentPrepared日志输出了哪些属性源。定位后就能判断谁在“抢”配置。另外通过spring.config.additional-location可以追加外部配置文件目录spring.config.import可以在 2.4 之后的版本里引入其他配置中心来源。组合使用时要谨慎因为外部化配置一旦多起来优先级冲突会直接演变成生产事故。3.4 应用事件与 Runner 的执行时机很多团队在启动流程里会写预加载逻辑比如预热缓存、预加载字典、初始化线程池常见的写法有两种实现ApplicationRunner或者实现CommandLineRunner。区别在于ApplicationRunner拿到的是封装好的ApplicationArguments而CommandLineRunner拿到的是原始字符串数组其余没有本质区别。Spring Boot 执行顺序是先执行所有ApplicationRunner和CommandLineRunner之后再发ApplicationReadyEvent。也就是说如果你在 Runner 里做了耗时操作服务虽然已经能“listen”端口但访问时会有一段空窗期直到 Ready 事件发出后才是真正完全可用。对需要精细化发布控制的场景建议在 Ready 事件之后再开始对外提供流量可以用 readiness 探针配合这一事件。Runner 之间如果有多套执行顺序需求可以用Order注解控制数字越小越先执行。这里有个小建议不要在 Runner 里做长时间阻塞任务也尽量不要在 Runner 里做重试逻辑把启动阶段的职责收敛到“校验、预热、上报”三件事上其他事情交给后台异步任务否则启动时长会被拖得很离谱。4. 启动故障排查最常踩的坑与排查套路4.1 启动慢的定位方法Spring Boot 项目启动慢了先要分清是容器阶段慢还是业务初始化慢。我在实际排查中一般按三步走第一步看Started Application in X seconds这行日志X 数值在 10 秒以内算正常超过就值得查。第二步确认--debug开启了没有看哪一段日志出现明显停顿如果日志没打点就用jstack直接抓线程堆栈看主线程卡在哪个方法上。第三步重点怀疑几个常见慢点数据库连接池初始化慢比如连接池创建时就去 ping 数据库数据库网络异常导致超时。Redis、消息队列等中间件连接慢连接超时配置过长。DNS 解析慢尤其在某些内部环境反解主机名可能卡住几秒。安全框架初始化慢大量权限声明的加载与注册。字节码增强CGLIB 代理大量类时启动阶段会明显变慢。有一个我踩过的坑某个服务启动后要等 30 秒才监听端口日志里一切正常。排查到最后发现是自定义的公司内部框架在prepareEnvironment阶段做了外网配置中心的长连接重试超时设了 5 次每次 6 秒。像这种发生在容器阶段之前的逻辑--debug看不到只能靠jstack或者打印阶段时间戳来定位。4.2 自动配置不生效的排查自动配置不生效先不要改代码按下面这个顺序排查。确认依赖确实进到了 classpath。用mvn dependency:tree或者查看最终打包的 jar 里有没有对应类最简单的方法是看MANIFEST和BOOT-INF/lib目录。确认自动配置没有被排除。检查spring.autoconfigure.exclude配置SpringBootApplication(exclude ...)属性以及是否有AutoConfigurationImportFilter实现类在过滤。用--debug看 Negative matches里面会直接列出条件不满足的原因。如果是自研模块检查AutoConfiguration.imports文件是否放在META-INF/spring/目录下且编码是 UTF-8。旧版本项目还可能沿用spring.factories但 Spring Boot 3.x 不再兼容。我曾经遇到一个诡异情况自动配置类的ConditionalOnClass明明匹配但配置类就是没加载。后来发现是同一个 class 名在两个 jar 里都有classpath 顺序导致加载了旧版本而旧版本里的注解元数据不一致。解决办法是统一依赖版本排除旧 jar。排查这种问题的核心思路就一句话先确认候选类被加载了再确认条件通过了最后确认 Bean 注册成功了三步分别打点。4.3 端口冲突与其他启动失败场景端口冲突是启动失败里高频的一种报错一般是Web server failed to start. Port 8080 was already in use.处理方式本地开发用系统命令找到占用 8080 端口的进程杀掉后重试。线上部署不建议直接改端口建议检查是否同一台机器上重复部署了服务或确认注册中心里端口分配是否正确。如果只是临时需要换端口命令行--server.port0可以让系统随机选一个可用端口适合本地联调。另一类常见失败是BeanCreationException导致启动直接终止。看到这个异常不要直接翻最下面往上看 Caused by大部分真正的根因都在后面几行。比如连接池初始化失败、某个 Bean 构造方法里远程调用超时等。值得注意的是Spring Boot 2.6 起默认禁止循环依赖如果你在升级版本后突然出现The dependencies of some of the beans in the application context form a cycle的报错而代码逻辑一直正常多半是项目的循环依赖被新版本默认策略挡住了。临时方案是设置spring.main.allow-circular-referencestrue但不建议长期开根子上应该打散 Bean 依赖图。4.4 版本升级时常见的启动问题Spring Boot 版本升级也是启动问题的高发期特别是大版本比如 2.x 升 3.x。这些是我实际遇到过的类型JDK 版本不满足Spring Boot 3.x 要求 JDK 17 及以上直接编译失败或启动报UnsupportedClassVersionError。javax 到 jakarta3.x 里 Servlet、JPA 等包的命名空间从javax.*改成了jakarta.*。没改的代码在启动阶段就会报 ClassNotFound典型的是javax.servlet相关依赖。自动配置加载方式变化3.x 不再通过spring.factories读取 EnableAutoConfiguration旧的 starter 需要同步更新。配置属性变更比如 Redis 相关配置从spring.redis.*迁移到spring.data.redis.*还按照老配置写启动不报错但配置会静默失效。默认行为变化除了循环依赖默认禁止还有spring.main.allow-bean-definition-overriding的默认值也在不同版本有差异导致覆盖注册的 Bean 在升级后直接失败。升级之前建议先看官方迁移文档并在本地把debugtrue打开跑一遍完整启动同时对比两版的自动配置报告手工核对哪些配置项被命中、哪些被跳过。这个动作看起来繁琐但比上线后半夜排查强得多。最后再分享一个我个人的习惯每次接手一个陌生的 Spring Boot 项目我都会先加--debug跑一次启动把 Positive matches 和 Negative matches 存档留存。后面对比版本升级、排查“突然不生效”的问题时这份报告就是最可靠的地图。启动原理这个东西其实不是让人背源码而是为了在出问题的时候能顺着那条链路快速找到怀疑点。你能从main方法一路说清楚环境准备、自动配置、容器启动、事件通知这几段就已经足够应付绝大多数日常疑难杂症了。
写了好几年Java我一直觉得Spring Boot最神奇的地方就是那一行SpringApplication.run。不知道你有没有好奇过为什么只写一个SpringBootApplication再执行一个run方法一个能处理请求的Web服务就起来了这背后不是魔法而是一套设计得相当精密的启动流程。搞懂它不只是为了面试更是在线上遇到启动慢、自动配置不生效、端口起不来这类问题时能顺着链路快速定位的思路基础。这篇文章我会从启动入口拆起逐步讲到环境准备、自动配置、内嵌容器和事件机制最后分享一些我自己排查启动故障时积累的经验。适合刚接触 Spring Boot、想从“会用”进阶到“懂原理”的同学也适合工作一两年的后端开发来查漏补缺。1. Spring Boot 启动的宏观链路从 main 方法到服务就绪1.1 启动入口的两段式构造先说结论。Spring Boot 的启动入口是固定的三板斧哪怕项目再复杂最后都会收敛到那一行SpringApplication.run上。很多新手以为这行代码做了“启动一个 Tomcat”这么简单的事实际上它内部被拆成了两段先new SpringApplication(主类.class)再调用这个实例的run(args)。第一段构造过程里有几件关键事值得展开讲。public SpringApplication(ResourceLoader resourceLoader, Class?... primarySources) { this.webApplicationType WebApplicationType.deduceFromClasspath(); this.bootstrapRegistryInitializers new ArrayList( getSpringFactoriesInstances(BootstrapRegistryInitializer.class)); this.initializers new ArrayList( getSpringFactoriesInstances(ApplicationContextInitializer.class)); this.listeners new ArrayList( getSpringFactoriesInstances(ApplicationListener.class)); this.mainApplicationClass deduceMainApplicationClass(); }推断 Web 应用类型。Spring Boot 启动时会扫一遍 classpath看有没有org.springframework.web.servlet.DispatcherServlet、jakarta.servlet.Servlet、org.springframework.web.reactive.DispatcherHandler这些类从而判断当前应用是传统的 Servlet Web 应用还是响应式的 Reactive Web 应用或者根本就是个非 Web 应用。这一步直接决定了后面创建哪种 ApplicationContext。加载三组 SPI。从约定文件里把BootstrapRegistryInitializer、ApplicationContextInitializer、ApplicationListener的实现类全部实例化出来。注意这里用的是getSpringFactoriesInstances本质就是读取 classpath 下所有 jar 里的约定配置再做去重和实例化。这就是为什么你引入某个 Starter 后它的自动配置、监听器天然会被感知到不需要写一行注册代码。推断主启动类。通过当前线程的堆栈找到包含 main 方法的那个类。网上很多教程会说“主类必须包在根包下”其实 Spring Boot 为了兼容非标准布局提供了一套兜底手段直接扫栈。如果你自己写的工具里也调用SpringApplication.run要小心主类推断可能不准确这算是比较少人注意的坑。1.2 run() 方法的核心执行节奏Spring Boot 2.x 的 run 方法核心流程我做了精简把骨架留出来。public ConfigurableApplicationContext run(String... args) { StopWatch stopWatch new StopWatch(); stopWatch.start(); DefaultBootstrapContext bootstrapContext createBootstrapContext(); SpringApplicationRunListeners listeners getRunListeners(args); listeners.starting(bootstrapContext, this.mainApplicationClass); ConfigurableEnvironment environment prepareEnvironment(listeners, bootstrapContext, args); printBanner(environment); ConfigurableApplicationContext context createApplicationContext(environment); // ...异常报告器、上下文加工、刷新、启动后处理省略 refreshContext(context); afterRefresh(context, applicationArguments); stopWatch.stop(); listeners.started(context, timeTakenToStartup); callRunners(context, applicationArguments); listeners.ready(context, timeTakenToReady); return context; }我把这段流程按顺序和阶段总结成一张表方便你对照。阶段关键动作对应事件启动计时创建 StopWatch记录启动总耗时无监听器开始通知所有运行监听器应用开始启动ApplicationStartingEvent环境准备加载默认属性、命令行参数、多 profile 配置ApplicationEnvironmentPreparedEventBanner 打印输出启动 Banner可自定义/关闭无上下文创建按应用类型创建 AnnotationConfigServletWebServerApplicationContext 等ApplicationContextInitializedEvent上下文刷新执行 Bean 定义解析、注册、实例化Tomcat 在此阶段启动ApplicationPreparedEvent、Spring 容器事件启动完成启动计时结束触发启动完成事件ApplicationStartedEventRunner 执行执行 ApplicationRunner / CommandLineRunner无就绪通知应用完全就绪可以接收流量ApplicationReadyEvent注意一个容易误解的地方在 Spring Boot 的启动日志里Started Application in X seconds出现的位置对应 ApplicationStartedEvent但在它之前其实内嵌 Tomcat 已经启动并占用了端口。真正能对外提供服务是等 ApplicationReadyEvent 发出之后。中间差的那点时间通常就是各种 Runner 和PostConstruct的预热逻辑。1.3 三种 ApplicationContext 的创建路径Spring Boot 不像传统 Spring 项目那样要你手动选ClassPathXmlApplicationContext还是AnnotationConfigApplicationContext它根据第一步推断出的 Web 应用类型自动创建。SERVLET 类型创建AnnotationConfigServletWebServerApplicationContext。它会注册默认的DispatcherServlet、过滤器链、内嵌容器管理等相关 Bean。REACTIVE 类型创建AnnotationConfigReactiveWebServerApplicationContext。走 WebFlux 那一套内嵌容器可能是 Netty。NONE 类型创建AnnotationConfigApplicationContext。比如命令行跑批任务、定时任务的应用就不会启动任何 Web 容器。对大部分业务系统来说你永远只会用到第一种。但这个推断机制告诉我们一件事如果你不小心引入了一个 Web 相关依赖而你的应用本来不需要 Web 容器启动时可能会出现Web server failed to start这类莫名其妙的错。排查的思路不是去怀疑配置写错了而是先把应用类型拉回预期。2. 自动配置是怎么“自动”起来的SPI 与条件装配2.1 SpringBootApplication 拆开看启动原理很多人讲不清楚是因为把两个概念混在了一起Spring 容器的启动和 Spring Boot 的自动配置。前者是“把 Bean 装进来”后者是“决定装哪些 Bean”。拆开看就清晰了。SpringBootApplication是一个合成注解它等价于下面三条SpringBootConfiguration本质是Configuration标记这是一个配置类。EnableAutoConfiguration开启自动配置机制这是整个 Spring Boot 的灵魂。ComponentScan扫描当前包及其子包下的Component、Service、Repository、Controller等组件。这里有个经典坑如果把ComponentScan的 basePackage 改成了其他包而且又没包含主类所在的包那么很多本来应该被扫描到的业务 Bean 会静默消失。所以大型项目用SpringBootApplication时要么别乱改扫描路径要么把扫描范围显式放到足够大的公共包上。EnableAutoConfiguration内部通过Import(AutoConfigurationImportSelector.class)引入一个导入选择器这个类会在解析配置阶段被触发返回一组自动配置的类全限定名。接下来要说的加载机制就集中在这个导入选择器上。2.2 自动配置候选的加载来源手动深入AutoConfigurationImportSelector的时候你会看到这些关键方法getCandidateConfigurations()拿到所有自动配置候选类名。getExclusionAutoConfigurations()处理spring.autoconfigure.exclude和EnableAutoConfiguration(exclude...)的排除清单。filter()用一组条件过滤器把不满足条件的配置类从候选列表中剔除。removeDuplicates()去重。sort()按照自动配置类上的AutoConfigureOrder、AutoConfigureBefore、AutoConfigureAfter排序。候选类名从哪里来Spring Boot 2.7 之前是META-INF/spring.factories文件里的org.springframework.boot.autoconfigure.EnableAutoConfiguration配置项2.7 开始引入新的META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports3.x 起彻底抛弃 spring.factories 这条通道。# spring.factories 形式2.7 以前 org.springframework.boot.autoconfigure.EnableAutoConfiguration\ com.example.demo.config.MyAutoConfiguration # AutoConfiguration.imports 形式2.7 com.example.demo.config.MyAutoConfiguration你引入一个第三方 Starter 时它 jar 包里如果带了这个 imports 文件启动时就会被 Spring Boot 读到。这也是为什么你只需要引入依赖不用手动Import配置类的原因。自己写公共模块想做得方便一点也应该按这个形式提供自动配置而不是让使用方手动 import。2.3 条件装配的常见套路加载进来的自动配置类不可能全都生效。比如你的项目没引入 Redis 客户端Redis 自动配置就应该自动放弃。Spring Boot 用一堆Conditional注解来完成这种判断常见的有ConditionalOnClassclasspath 中存在某个类才生效。ConditionalOnMissingBean容器中没有某个 Bean 才生效。ConditionalOnBean容器中存在某个 Bean 才生效。ConditionalOnProperty配置项满足匹配值才生效。ConditionalOnWebApplication应用是 Web 应用才生效。拿RedisAutoConfiguration举例它的类头大致长这样AutoConfiguration ConditionalOnClass(RedisOperations.class) EnableConfigurationProperties(RedisProperties.class) Import({ LettuceConnectionConfiguration.class, JedisConnectionConfiguration.class }) public class RedisAutoConfiguration { Bean ConditionalOnMissingBean(name redisTemplate) public RedisTemplateObject, Object redisTemplate(RedisConnectionFactory factory) throws UnknownHostException { // ... } }第一层ConditionalOnClass(RedisOperations.class)决定了只要 classpath 里没有 Redis 驱动整个配置类直接跳过。第二层对 redisTemplate 这个 Bean 的判断如果业务代码里自己定义了一个名为redisTemplate的 Bean自动配置的默认模板就不再注册这遵循“用户可以覆盖默认实现”的设计思想。这里有个非常容易踩的坑ConditionalOnMissingBean对 Bean 的判断发生在注册阶段而不是解析阶段。如果你的业务 Bean 是靠ComponentScan扫描进来的Spring Boot 会先处理自动配置类再扫描主程序包时ConditionalOnMissingBean有可能误判。要规避它通常是调整自动配置类与扫描的先后顺序或者不用缺失判断专门写一个ConditionalOnProperty来决定是否启用。2.4 用 --debug 拿到专属自动配置报告排查“某个自动配置为什么没生效”的最快方法是启动时加参数或者在application.properties里写debugtrue。启动之后日志里会出现两段关键输出Positive matches命中的自动配置类后面会列出命中的条件注解。Negative matches未命中的自动配置类并且会说明是哪个条件不满足。比如说你怀疑某个ConfigurationProperties没生效看 Negative matches 里会直接提示ConditionalOnProperty的哪一项没匹配上。有些项目日志出于安全考虑关闭了启动信息那就在本地启动时专门开一次--debug看完再关。这个能力在生产排查同类问题时也很有价值但要注意日志量大不要在高峰时段随便开。3. Web 环境的启动细节内嵌容器与监听器机制3.1 内嵌 Tomcat 的启动链路Spring Boot 默认的 Web 容器是 Tomcat但你没有手动写过 Tomcat 配置容器是怎么起来的要追溯到ServletWebServerFactoryAutoConfiguration这个自动配置类。解析ServletWebServerFactoryAutoConfiguration时发现 classpath 里有Tomcat.class于是往容器里注册TomcatServletWebServerFactory。刷新上下文阶段ServletWebServerFactoryAutoConfiguration.BeanPostProcessorsRegistrar会注册一堆后置处理器其中WebServerFactoryCustomizerBeanPostProcessor会把你在配置类里定义的WebServerFactoryCustomizer应用到工厂上端口、压缩、超时等配置都在这时被改写。WebServerStartStopLifecycle或者ServletWebServerApplicationContext.onStartup阶段会调用factory.getWebServer()这个方法内部创建真实的 Tomcat 对象设置 Connector准备 Context最后调用tomcat.start()绑定端口。整个过程最容易被忽略的是Tomcat 在这里实际上是一段“容器生命周期”管理而不是单纯的 Socket 服务启动。Spring MVC 的DispatcherServlet是通过DispatcherServletRegistrationBean注册进 Tomcat 的 Servlet 上下文里的。把这两件事分开理解后遇到“端口起不来”和“请求 404”两类问题时你就能快速定位到底是容器层的问题还是 Servlet 层的问题。3.2 事件广播与监听器启动过程的“导航信号”Spring Boot 启动全程会发出多个事件这些事件统称SpringApplicationEvent。它们走的是SpringApplicationRunListeners而不是 Spring 容器的事件广播器。区别在于前者发生在容器刷新之前、之中、之后的各种阶段后者至少在上下文刷新完成后才会完整介入。我整理了一份事件速查表排查问题时可以直接对照。事件触发时机典型用途ApplicationStartingEvent启动开始环境未构建记录启动日志、设置载入参数ApplicationEnvironmentPreparedEvent环境已准备容器未创建根据环境调整日志级别、过滤配置项ApplicationContextInitializedEvent上下文已创建Bean 未开始加载扩展点注册ApplicationPreparedEvent准备刷新上下文预热数据源、预创建连接池ApplicationStartedEvent上下文已刷新Runner 未执行上报启动状态、执行轻量校验ApplicationReadyEvent全部就绪发心跳、预热缓存、开任务ApplicationFailedEvent启动失败保存故障现场、推送告警举个例子我之前遇到一个场景某个服务要求上线后立刻把注册信息报到配置中心但启动日志显示服务正常配置中心里却迟迟没有数据。后来发现数据上报逻辑写在ApplicationStartedEvent监听里而这个时候 Runner 还没跑完注册中心客户端连接的超时时间偏大导致上报丢失。调整到ApplicationReadyEvent之后问题立刻消失。这就是事件时序对业务代码的直接影响了。3.3 配置加载的顺序与优先级环境准备阶段还有个容易被小看的能力属性来源的合并。Spring Boot 的ConfigurableEnvironment会维护一个属性源列表后加入的覆盖先加入的。默认优先级从高到低大致是这个顺序命令行参数--server.port8090Java 系统属性-Dserver.port8090操作系统环境变量SERVER_PORT8090application-{profile}.yml如 application-prod.ymlapplication.yml/ application.properties默认属性代码里通过setDefaultProperties设置的所以“application.yml 里明明写了端口 8080启动后却是 8090”这种事大概率不是文件写错了而是命令行参数或者环境变量的优先级把配置覆盖了。排查这类问题的方法是写一个临时Environment打印所有属性源或者启动日志里临时打开debug看看EnvironmentPrepared日志输出了哪些属性源。定位后就能判断谁在“抢”配置。另外通过spring.config.additional-location可以追加外部配置文件目录spring.config.import可以在 2.4 之后的版本里引入其他配置中心来源。组合使用时要谨慎因为外部化配置一旦多起来优先级冲突会直接演变成生产事故。3.4 应用事件与 Runner 的执行时机很多团队在启动流程里会写预加载逻辑比如预热缓存、预加载字典、初始化线程池常见的写法有两种实现ApplicationRunner或者实现CommandLineRunner。区别在于ApplicationRunner拿到的是封装好的ApplicationArguments而CommandLineRunner拿到的是原始字符串数组其余没有本质区别。Spring Boot 执行顺序是先执行所有ApplicationRunner和CommandLineRunner之后再发ApplicationReadyEvent。也就是说如果你在 Runner 里做了耗时操作服务虽然已经能“listen”端口但访问时会有一段空窗期直到 Ready 事件发出后才是真正完全可用。对需要精细化发布控制的场景建议在 Ready 事件之后再开始对外提供流量可以用 readiness 探针配合这一事件。Runner 之间如果有多套执行顺序需求可以用Order注解控制数字越小越先执行。这里有个小建议不要在 Runner 里做长时间阻塞任务也尽量不要在 Runner 里做重试逻辑把启动阶段的职责收敛到“校验、预热、上报”三件事上其他事情交给后台异步任务否则启动时长会被拖得很离谱。4. 启动故障排查最常踩的坑与排查套路4.1 启动慢的定位方法Spring Boot 项目启动慢了先要分清是容器阶段慢还是业务初始化慢。我在实际排查中一般按三步走第一步看Started Application in X seconds这行日志X 数值在 10 秒以内算正常超过就值得查。第二步确认--debug开启了没有看哪一段日志出现明显停顿如果日志没打点就用jstack直接抓线程堆栈看主线程卡在哪个方法上。第三步重点怀疑几个常见慢点数据库连接池初始化慢比如连接池创建时就去 ping 数据库数据库网络异常导致超时。Redis、消息队列等中间件连接慢连接超时配置过长。DNS 解析慢尤其在某些内部环境反解主机名可能卡住几秒。安全框架初始化慢大量权限声明的加载与注册。字节码增强CGLIB 代理大量类时启动阶段会明显变慢。有一个我踩过的坑某个服务启动后要等 30 秒才监听端口日志里一切正常。排查到最后发现是自定义的公司内部框架在prepareEnvironment阶段做了外网配置中心的长连接重试超时设了 5 次每次 6 秒。像这种发生在容器阶段之前的逻辑--debug看不到只能靠jstack或者打印阶段时间戳来定位。4.2 自动配置不生效的排查自动配置不生效先不要改代码按下面这个顺序排查。确认依赖确实进到了 classpath。用mvn dependency:tree或者查看最终打包的 jar 里有没有对应类最简单的方法是看MANIFEST和BOOT-INF/lib目录。确认自动配置没有被排除。检查spring.autoconfigure.exclude配置SpringBootApplication(exclude ...)属性以及是否有AutoConfigurationImportFilter实现类在过滤。用--debug看 Negative matches里面会直接列出条件不满足的原因。如果是自研模块检查AutoConfiguration.imports文件是否放在META-INF/spring/目录下且编码是 UTF-8。旧版本项目还可能沿用spring.factories但 Spring Boot 3.x 不再兼容。我曾经遇到一个诡异情况自动配置类的ConditionalOnClass明明匹配但配置类就是没加载。后来发现是同一个 class 名在两个 jar 里都有classpath 顺序导致加载了旧版本而旧版本里的注解元数据不一致。解决办法是统一依赖版本排除旧 jar。排查这种问题的核心思路就一句话先确认候选类被加载了再确认条件通过了最后确认 Bean 注册成功了三步分别打点。4.3 端口冲突与其他启动失败场景端口冲突是启动失败里高频的一种报错一般是Web server failed to start. Port 8080 was already in use.处理方式本地开发用系统命令找到占用 8080 端口的进程杀掉后重试。线上部署不建议直接改端口建议检查是否同一台机器上重复部署了服务或确认注册中心里端口分配是否正确。如果只是临时需要换端口命令行--server.port0可以让系统随机选一个可用端口适合本地联调。另一类常见失败是BeanCreationException导致启动直接终止。看到这个异常不要直接翻最下面往上看 Caused by大部分真正的根因都在后面几行。比如连接池初始化失败、某个 Bean 构造方法里远程调用超时等。值得注意的是Spring Boot 2.6 起默认禁止循环依赖如果你在升级版本后突然出现The dependencies of some of the beans in the application context form a cycle的报错而代码逻辑一直正常多半是项目的循环依赖被新版本默认策略挡住了。临时方案是设置spring.main.allow-circular-referencestrue但不建议长期开根子上应该打散 Bean 依赖图。4.4 版本升级时常见的启动问题Spring Boot 版本升级也是启动问题的高发期特别是大版本比如 2.x 升 3.x。这些是我实际遇到过的类型JDK 版本不满足Spring Boot 3.x 要求 JDK 17 及以上直接编译失败或启动报UnsupportedClassVersionError。javax 到 jakarta3.x 里 Servlet、JPA 等包的命名空间从javax.*改成了jakarta.*。没改的代码在启动阶段就会报 ClassNotFound典型的是javax.servlet相关依赖。自动配置加载方式变化3.x 不再通过spring.factories读取 EnableAutoConfiguration旧的 starter 需要同步更新。配置属性变更比如 Redis 相关配置从spring.redis.*迁移到spring.data.redis.*还按照老配置写启动不报错但配置会静默失效。默认行为变化除了循环依赖默认禁止还有spring.main.allow-bean-definition-overriding的默认值也在不同版本有差异导致覆盖注册的 Bean 在升级后直接失败。升级之前建议先看官方迁移文档并在本地把debugtrue打开跑一遍完整启动同时对比两版的自动配置报告手工核对哪些配置项被命中、哪些被跳过。这个动作看起来繁琐但比上线后半夜排查强得多。最后再分享一个我个人的习惯每次接手一个陌生的 Spring Boot 项目我都会先加--debug跑一次启动把 Positive matches 和 Negative matches 存档留存。后面对比版本升级、排查“突然不生效”的问题时这份报告就是最可靠的地图。启动原理这个东西其实不是让人背源码而是为了在出问题的时候能顺着那条链路快速找到怀疑点。你能从main方法一路说清楚环境准备、自动配置、容器启动、事件通知这几段就已经足够应付绝大多数日常疑难杂症了。
