springboot自动配置失效的根本原因在于类路径、条件注解或扫描路径偏差，需按四步排查：一查autoconfiguration.imports文件是否存在及内容正确；二验@conditional注解是否全部满足，借助debug日志或/actuator/conditions端点；三检@componentscan、@springbootapplication排除项及启动类包位置；四排多模块依赖版本一致性、重复starter引入及autoconfigure作用域。
SpringBoot自动配置失效时，应用启动后关键Bean缺失、功能未启用、健康检查失败，根本原因往往藏在类路径、条件注解或扫描路径的细微偏差里。
第一步：确认自动配置类是否进入候选列表
打开项目根目录下的 target/classes/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports（Maven）或 build/resources/main/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports（Gradle），检查你期望的自动配置类（如 DataSourceAutoConfiguration）是否真实存在于该文件中。
如果文件不存在，说明 starter 依赖未正确引入；如果存在但你的配置类不在其中，说明模块未被 Spring Boot 识别为自动配置提供方——此时需检查模块是否声明了 spring-boot-autoconfigure 作为 compile 依赖，且资源路径严格为 META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports。
第二步：验证条件注解是否全部满足
启用 DEBUG 日志是最快手段：在 application.properties 中添加 logging.level.org.springframework.boot.autoconfigure=DEBUG，重启应用，观察控制台输出中类似 Excluding auto-configuration class xxx because xxx 的日志行。
常见不满足条件包括：【@ConditionalOnClass 检查的类未在 classpath】（例如用了 spring-boot-starter-data-jpa 却漏了 HikariCP 或 Hibernate 依赖）、【@ConditionalOnProperty 对应的属性未设置或值为 false】（如 spring.redis.enabled=true 未配，而配置类要求该属性为 true）。
若日志无明确排除信息，访问 /actuator/conditions 端点（需引入 spring-boot-starter-actuator 并暴露该端点），它会逐条列出每个自动配置类的匹配状态和失败原因。
第三步：检查包扫描与组件加载冲突
方法一：查看主启动类是否被错误标注了 @ComponentScan。如果写了 @ComponentScan("com.example")，而自动配置类在 org.springframework.boot.autoconfigure 包下，就会被强制纳入扫描——这反而导致 Spring Boot 内部机制误判并跳过该类。
方法二：检查是否存在显式排除。搜索项目代码中是否出现 @SpringBootApplication(exclude = ...) 或 spring.autoconfigure.exclude=... 配置项，哪怕只排除了一个类，也可能引发级联失效（例如排除了 JpaBaseConfiguration，会导致整个 JPA 自动配置链中断）。
方法三：确认启动类位置。Spring Boot 默认以主类所在包为根包进行扫描。如果启动类位于 com.example.util.Application，则 com.example.config 下的手动配置类可能被漏扫——这时必须显式用 @SpringBootApplication(scanBasePackages = "com.example") 覆盖默认行为。
第四步：排查多模块与依赖传递干扰
第一步：执行 mvn dependency:tree -Dincludes=org.springframework.boot（Maven）或 ./gradlew dependencies --include-used --configuration runtimeClasspath（Gradle），确认所有模块使用的 spring-boot-autoconfigure 版本完全一致。版本错位（如模块A用3.2.0，模块B用3.1.5）会导致 AutoConfiguration.imports 解析失败或条件注解类不可见。
第二步：检查模块间是否重复引入 starter。例如模块A已依赖 spring-boot-starter-web，模块B又单独引入，可能触发两次 WebMvcAutoConfiguration 加载，造成 Bean 定义冲突或覆盖。
第三步：确认模块A的自动配置类是否被正确导出。在模块A的 pom.xml 中，spring-boot-autoconfigure 必须声明为 compile 作用域（非 provided 或 test），否则模块B编译时无法读取其 AutoConfiguration.imports 文件。
