SpringBoot 3.x中starter失效主因是spring.factories被移除，需改用META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports声明配置类，并将@Configuration替换为@AutoConfiguration。
SpringBoot项目引入自定义starter后，Bean注入失败、配置类未加载、@ControllerAdvice不触发——根本不是代码写错了，而是自动配置声明路径在SpringBoot 3.x中已彻底变更。
确认是否为SpringBoot 3.x版本导致的失效
打开项目pom.xml，检查parent中的spring-boot-starter-parent版本号：若为3.0.0及以上（如3.1.0、3.3.1），则【spring.factories文件已被完全移除，任何写在其中的配置类都不会被加载】。这是最常被忽略的前提，90%的“starter不生效”问题都卡在这里。
启动时加JVM参数-Dlogging.level.org.springframework.boot.autoconfigure=DEBUG，观察控制台是否输出"Loaded AutoConfigurationImportSelector"及后续扫描到你starter中配置类的日志——没有，就说明声明路径失效。
将spring.factories迁移至AutoConfiguration.imports
删除项目resources/META-INF/spring.factories文件（如果还存在）。
在相同目录下新建文件：META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports。
在该文件中，**每行写一个自动配置类的全限定名**，不能有空格、分号或注释：
com.example.starter.config.MyAutoConfiguration
com.example.starter.config.ExceptionHandlerAutoConfiguration
注意：这个文件名必须一字不差，大小写敏感，且路径必须是META-INF/spring/下，不是META-INF/根目录。
重构自动配置类注解
原写法（SpringBoot 2.x兼容，3.x不推荐）：
@Configuration
@ConditionalOnClass(DataSource.class)
@EnableConfigurationProperties(MyProperties.class)
改为SpringBoot 3.x标准写法：
@AutoConfiguration
@ConditionalOnClass(DataSource.class)
@EnableConfigurationProperties(MyProperties.class)
【@AutoConfiguration替代@Configuration+@ConditionalOn组合，是SpringBoot 3.x自动配置类的唯一合法入口注解】。继续用@Configuration会导致该类被当作普通配置类加载，失去条件判断能力，且无法参与自动配置排序（@AutoConfigureBefore/@AutoConfigureAfter失效）。
将 Spring Boot 2.7 项目升级到 Spring Boot 3.5 的实战流程，覆盖版本基线、依赖坐标替换、Jakarta 迁移、配置兼容、异步上下文传递改造与验证门禁。用于企业多模块 Maven 项目升级与排障。
验证@ControllerAdvice等组件是否被扫描
方法一：显式启用组件扫描
在自动配置类上添加@ComponentScan("com.example.starter.advice")，确保包含@ControllerAdvice所在包。SpringBoot 3.x默认不会扫描starter内部的非配置类组件。
方法二：用@Import注册
在自动配置类中添加@Bean方法返回@ControllerAdvice实例：
@Bean
@ConditionalOnMissingBean
public GlobalExceptionAdvice globalExceptionAdvice() {
return new GlobalExceptionAdvice();
}
这比依赖@ComponentScan更可靠，避免因包路径不匹配导致Advice未注册。
排除干扰项：检查exclude配置
第一步：搜索整个项目，查找@SpringBootApplication(exclude =或spring.autoconfigure.exclude=。
第二步：确认你starter中配置类的全限定名**未出现在任何exclude列表中**。例如，若starter配置类是com.example.starter.config.MyAutoConfiguration，而application.yml里写了spring.autoconfigure.exclude=com.example.starter.config，则整个包都会被跳过。
第三步：临时注释掉所有exclude配置，重启验证。若此时starter生效，说明问题出在排除逻辑上。
强制触发自动配置加载（调试用）
在主应用启动类上，使用@Import显式导入你的配置类：
@SpringBootApplication
@Import({MyAutoConfiguration.class, ExceptionHandlerAutoConfiguration.class})
如果此时Bean能正常注入、Advice开始捕获异常，说明自动配置类本身无问题，问题100%出在AutoConfiguration.imports声明或类路径扫描环节。
这一步操作起来很简单，直接把配置类名填进@Import括号里就行。
