自动配置类未被扫描到，首要排查META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports文件路径是否正确、内容是否规范，其次验证类是否被ClassLoader加载及条件注解是否满足。
SpringBoot自定义自动配置类写好了、注册了、也加了条件注解，但启动时完全没日志、Bean没注入、切面不触发——说明自动配置根本没被Spring Boot扫描到或跳过了条件判断。
确认自动配置类是否被Spring Boot识别
第一步：检查项目构建后jar/war包中是否存在 【META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports】 文件。该路径必须严格匹配，不能是 spring.factories（Spring Boot 2.7+ 已废弃）、不能是 META-INF.spring（IDE误识别为包名）、也不能是 META-INF/spring/imports（缺关键路径段）。
第二步：打开该文件，确认内容是纯文本、每行一个全限定类名，末尾无空格、无BOM头、无注释符号#——Spring Boot会逐行读取并反射加载，遇到非法字符或类名拼写错误直接跳过整行。
第三步：在自动配置类的类体外添加静态代码块，例如：static { System.out.println("✅ IdempotentAutoConfiguration loaded"); }。若控制台未输出，证明该类未被任何ClassLoader加载，问题一定出在注册路径或类路径上。
验证条件注解是否满足
方法一：启用自动配置调试日志，在 application.properties 中添加：
logging.level.org.springframework.boot.autoconfigure=DEBUG
方法二：启动后访问 /actuator/conditions 端点（需引入 spring-boot-starter-actuator），搜索你的自动配置类名，查看“Positive matches”和“Negative matches”两栏——若出现在后者，点击展开即可看到具体不满足哪条 @ConditionalOnXXX 条件。
常见陷阱：@ConditionalOnClass 要求类必须在当前 classpath 下存在（不仅是编译期依赖），比如你写了 @ConditionalOnClass(RedisTemplate.class)，但实际只引入了 spring-boot-starter-data-redis 的 starter，而没真正引入 redis.clients:jedis 或 io.lettuce:lettuce-core，条件就会失败。
排查包扫描与依赖可见性
第一步：确认自动配置类所在模块已被主应用模块正确依赖。Maven 中检查
将 Spring Boot 2.7 项目升级到 Spring Boot 3.5 的实战流程，覆盖版本基线、依赖坐标替换、Jakarta 迁移、配置兼容、异步上下文传递改造与验证门禁。用于企业多模块 Maven 项目升级与排障。
第二步：若为多模块项目，检查主启动类所在模块的 @SpringBootApplication 是否隐式覆盖了自动配置类的包路径。例如主类在 com.example.web，而自动配置类在 com.example.starter.config，此时必须显式声明 scanBasePackages = "com.example"，否则 @ComponentScan 默认只扫主类所在包及其子包，starter 包将被忽略。
第三步：在自动配置类上临时加上 @Configuration + @Import({YourBean.class})，再启动看 YourBean 是否能创建。若可以，说明自动配置机制本身被绕过，问题锁定在 AutoConfiguration.imports 注册或条件判断；若也不行，说明类加载器根本没触达该类——回到第一步重查文件路径和构建产物。
强制触发自动配置加载（仅调试用）
在主启动类的 main 方法最开头插入以下代码：
System.setProperty("org.springframework.boot.autoconfigure.AutoConfiguration.imports.debug", "true");
这会令 Spring Boot 在控制台打印所有尝试加载的自动配置类路径及失败原因，无需重启应用即可快速定位是文件未找到、类找不到，还是 SecurityManager 拦截了反射调用。
注意：此开关仅对开发调试有效，不可用于生产环境，且必须在 SpringApplication.run() 之前设置。
