Spring Boot自动配置失效需四步排查：一查Auto-configuration report确认配置是否进入候选；二查META-INF/spring/下注册文件路径是否正确；三验条件注解是否满足，通过DEBUG日志或/actuator/conditions端点；四核包扫描范围、依赖范围及Bean冲突。
SpringBoot不同版本自动配置失效时，无法靠单一手段定位问题，必须建立一套跨版本通用的排查路径，否则在2.x与3.x之间、甚至3.1与3.2之间反复踩坑。
第一步：确认自动配置是否进入候选列表
启动应用时添加 【--debug】 参数，或在 application.yml 中配置 debug: true。Spring Boot 会输出 Auto-configuration report，其中明确列出“Positive matches”（生效）和“Negative matches”（未生效）两类配置项。
重点查看你要验证的自动配置类是否出现在 Negative matches 列表中——如果连名字都没出现，说明它根本没被扫描到，后续所有排查都无意义。
若使用 Spring Boot 3.2+，报告位置可能移至 /actuator/autoconfig（需启用 Actuator 并暴露该端点）。
第二步：检查 META-INF/spring/ 下的注册文件路径
Spring Boot 2.7 及之前版本读取的是 【META-INF/spring.factories】；从 3.0 开始强制使用 【META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports】。
多模块项目中常见错误：IDEA 将 resources/META-INF/spring/ 文件夹误识别为 resources/META-INF.spring/，导致路径实际变成 resources/META-INF.spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports —— Spring Boot 完全忽略该路径。
解决方案：手动在资源目录下新建文件夹，逐级创建 META-INF → spring → org.springframework.boot.autoconfigure.AutoConfiguration.imports，不要依赖 IDE 自动生成。
第三步：验证条件注解是否满足
方法一：启用 DEBUG 日志级别
在 application.yml 中添加：logging.level.org.springframework.boot.autoconfigure: DEBUG
启动后搜索 “excluded” 或 “did not match”，日志会直接说明某配置类因 @ConditionalOnClass 缺失、@ConditionalOnProperty 未设置等原因被跳过。
方法二：调用 /actuator/conditions 端点（需引入 spring-boot-starter-actuator 并暴露 endpoints）
返回 JSON 中会按配置类分组，列出每一项条件是否匹配，比日志更结构化。
注意：Spring Boot 3.x 中部分条件注解语义已变更，例如 @ConditionalOnWebApplication(type = Type.REACTIVE) 在 Servlet 环境下永远不匹配，必须改为 Type.SERVLET。
第四步：确认包扫描与 Bean 加载顺序
第一步：检查主启动类所在包路径是否覆盖自动配置类所在包。
若自动配置类在 com.example.starter.config，而启动类在 com.example.util.Application，@ComponentScan 默认不会扫描到 com.example.starter。
第二步：若使用自定义 Starter，确保其依赖以 compile 范围引入，而非 provided 或 test。
Maven 中 【
第三步：检查是否存在同名 Bean 冲突。
Spring Boot 自动配置类中常用 @ConditionalOnMissingBean，一旦你在自己代码里声明了相同类型（如 DataSource）的 @Bean，自动配置就会静默跳过——此时日志中只会显示 “matched” 而非 “excluded”，极易误判。
