不知道你有没有过这样的经历项目跑得好好的某天顺手把Spring Boot版本从2.6升到2.7IDE里突然冒出一行黄色警告——spring.factories里配置的自动配置已废弃。我当时没太当回事直到后来同事负责的模块出现了一个“配置类明明写好了就是不生效”的问题排查到最后才发现都和这两个文件有关老的META-INF/spring.factories以及新引入的META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports。这篇文章我尽量用实际操作视角来聊这两份文件到底各自管什么、为什么Spring Boot要切换、怎么把一个现成的自定义starter迁到新机制以及迁移之后容易踩哪些隐蔽的坑。无论你是维护公司内部公共starter的老手还是刚接触自动配置机制的新人只要涉及Spring Boot的自定义能力这篇应该能帮你省下不少调试时间。1. 两个文件的前世今生自动配置到底靠谁发现1.1 spring.factories老资格的“万能注册表”很多人第一次接触spring.factories并不是因为它多好用而是因为排查某个自动配置为什么不生效时被指引着打开这个文件看了一眼一堆key\开头的属性类名用逗号连接格式不够直观但功能很强大。它的本质是Spring Framework里的一个通用扩展机制由SpringFactoriesLoader在classpath下扫描所有META-INF/spring.factories文件按照Properties格式解析再把每个key对应的类列表加载出来。对自动配置来说关键的key是org.springframework.boot.autoconfigure.EnableAutoConfiguration\ com.example.starter.MyAutoConfiguration,\ com.example.starter.OtherAutoConfiguration凡是在这个key下面列出的类都会被Spring Boot在启动阶段纳入自动配置候选名单之后逐个按Conditional系列注解判断是否生效。但这张“注册表”不止服务自动配置。ApplicationContextInitializer、EnvironmentPostProcessor、SpringApplicationRunListener、TypeExcludeFilter这些扩展点同样靠spring.factories里的不同key注册。换句话说它是一张“什么都能塞”的通用名单早期确实是灵活的但后来也成了问题。1.2 AutoConfiguration.imports一张更精简的“专用名单”Spring Boot 2.7开始官方引入了新的注册文件路径固定为META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports注意这个文件名不是随便起的它的格式是“包路径 .imports”相当于用文件路径声明了自己的命名空间。文件内容也简单得多不需要key不需要等号不需要反斜杠续行每行直接写一个自动配置类的全限定名即可。com.example.starter.MyAutoConfiguration com.example.starter.OtherAutoConfiguration读取逻辑由AutoConfigurationImportSelector完成匹配到的新文件优先级更高。Spring Boot 2.7的值传递机制里有一个ImportCandidates工具类专门负责从这个固定路径加载候选类再和旧版spring.factories里读到的结果合并去重。如果你打开一个Spring Boot 3.x的工程会看到几乎所有官方starter已经不再通过spring.factories注册自动配置了全部转到了.imports文件。这不是优化建议而是硬性要求。1.3 两个文件同时存在时谁说了算“那我两个文件都写上是不是就稳了”这是我在迁移时问过自己的第一个问题结论是看版本。在Spring Boot 2.7和2.7.x系列里两者是共存关系。系统会先读取AutoConfiguration.imports中的候选配置再读取spring.factories里EnableAutoConfiguration这个key下的候选配置然后合并去重。由于Spring Boot内部用LinkedHashSet保存结果重复的类名最终只会保留一份所以理论上不会因为同一个类出现在两个文件里就执行两次。到了Spring Boot 3.0情况彻底变了。自动配置的候选名单只会从AutoConfiguration.imports中读取spring.factories里哪怕写得再全也被直接忽略而且不会报错。这种“静默失效”是迁移过程中最阴险的问题后面我会专门展开。简单整理一下版本与文件支持的关系Spring Boot版本spring.factories自动配置AutoConfiguration.imports2.3 ~ 2.6支持不存在2.7 ~ 2.7.18支持已标记 deprecated支持优先读取3.0 及以上不再支持自动配置必须使用2. 为什么Spring Boot要抛弃spring.factories里的自动配置注册2.1 一个文件承载了太多职责分层被打破很多人把spring.factories当成“自动配置专用文件”但它其实是个大杂烩。同一种格式里既有自动配置类又有监听器又有初始化器还有各种过滤器。当IDE或静态分析工具看到这个文件时它没法凭内容判断某个条目到底属于哪类扩展点只能全量加载、全量parse。这种“什么都行”的设计对框架底层做优化非常不利。比如编译期就想把自动配置候选类整理出来提前校验或者构建插件想分析配置覆盖情况都得逐个遍历所有jar包里的spring.factories再靠字符串匹配key才能筛选出自动配置效率低不说还容易误判。新文件的路径直接带上了AutoConfiguration内容里也只需要类名从格式上就和“其他扩展点”做了彻底切割。自动配置就是自动配置别的机制请走spring.factories。这个改动我很喜欢它把十年积累下来的混乱命名空间一次性理顺了。2.2 构建期全量扫描与启动速度的“隐形开销”Spring Boot 3.0的目标之一是让启动过程更轻量。在这种目标下spring.factories的扫描方式显得越来越笨重每个jar包里都有一个同名文件系统要把它们全部找出来、全部加载、全部解析然后再按key分流。项目小的时候感觉不到但一个大型微服务系统里几十个starter的自动配置候选类可能堆积到上百个这部分耗时虽然不至于让启动变慢多少但每一次classpath扫描、每一份Properties解析都成了可以优化的点。.imports文件在这方面更干净路径更精确、内容更稀疏、按行读取类名即可不需要经过Properties解析层也不存在“key拼错了但没发现”的问题。命名本身还自带约束——文件名写错一个字符IDE和编译期都有机会发现而不是等到运行时静默失效。2.3 语义化约束把“配置错误”提前到编译期认知用spring.factories最难受的一点是如果你把key写错了比如少了个包名系统通常不会立刻报错项目能正常启动但你的自动配置就是不加载最后只能靠翻日志排查。而新机制把“自动配置候选文件”的路径固定成大写的完整包名文件建错位置就会直接找不到候选配置配合IDE的自动补全和代码提示错误暴露的时间点大大提前。另外AutoConfiguration注解的引入也是这次切换的重要一环。这个注解本质上是一个元注解组合内部包含了Configuration(proxyBeanMethods false)同时自带before、after属性用来替代原来散落在类上的AutoConfigureBefore和AutoConfigureAfter。换句话说新机制不仅仅是换了个放类名的文件连配置类本身的写法也一起规范了。3. 从spring.factories迁到AutoConfiguration.imports的实操3.1 先分清哪些条目能搬、哪些不能搬迁移的第一步不是建文件而是先打开你现有spring.factories逐个key审查。只有org.springframework.boot.autoconfigure.EnableAutoConfiguration这个key下的条目才属于自动配置可以搬到.imports。其余key代表的扩展机制继续留在spring.factories里一个都不能动。常见的不可搬迁key包括功能key是否需要迁移环境后置处理org.springframework.boot.env.EnvironmentPostProcessor否保留原文件应用上下文初始化器org.springframework.boot.context.ApplicationContextInitializer否保留原文件启动监听器org.springframework.boot.SpringApplicationRunListener否保留原文件类型排除过滤器org.springframework.boot.autoconfigure.AutoConfigurationImportListener否保留原文件自动配置org.springframework.boot.autoconfigure.EnableAutoConfiguration是迁移到imports如果你在迁移时图省事把EnvironmentPostProcessor这类条目连带放进了.imports启动时它不会按预期执行有的还会直接抛异常。因为新文件的读取路径只认自动配置候选类根本不会把它当成EnvironmentPostProcessor处理。3.2 新文件的路径与格式细节在资源目录下新建src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports文件内部直接写类名不要写任何前缀一行一个例如com.example.starter.MyAutoConfiguration com.example.starter.CacheAutoConfiguration com.example.starter.RetryAutoConfiguration有几个细节值得强调文件名必须完整复制成org.springframework.boot.autoconfigure.AutoConfiguration.imports少一个字母都不行。因为读取逻辑是按这个固定路径拼接的不存在“近似匹配”。文件编码建议用UTF-8类名里尽量不要出现任何中文注释避免部分Windows环境下读取异常。空行和注释符#可以存在不影响读取但为了整洁每行只放一个类。提示如果你用的是Maven务必确认资源文件被正确打进jar包。有的项目把资源文件放在src/main/java下导致打包遗漏这个问题在spring.factories时代也存在换了新文件名后更容易被忽略。3.3 模拟一个starter的完整迁移动手过程我在本地维护了一个模拟项目X结构很简单一个自动配置类SimpleServiceAutoConfiguration一个属性类SimpleServiceProperties外加一个服务类SimpleService。迁移前spring.factories里是这个样子org.springframework.boot.autoconfigure.EnableAutoConfiguration\ com.example.starter.SimpleServiceAutoConfiguration配置类本身的写法是Configuration(proxyBeanMethods false) EnableConfigurationProperties(SimpleServiceProperties.class) ConditionalOnClass(SimpleService.class) ConditionalOnProperty(prefix simple, name enabled, havingValue true, matchIfMissing true) public class SimpleServiceAutoConfiguration { Bean ConditionalOnMissingBean public SimpleService simpleService() { return new SimpleService(); } }迁移的第一步新建.imports文件并放入类名com.example.starter.SimpleServiceAutoConfiguration第二步把配置类上的Configuration替换为AutoConfigurationAutoConfiguration EnableConfigurationProperties(SimpleServiceProperties.class) ConditionalOnClass(SimpleService.class) ConditionalOnProperty(prefix simple, name enabled, havingValue true, matchIfMissing true) public class SimpleServiceAutoConfiguration { Bean ConditionalOnMissingBean public SimpleService simpleService() { return new SimpleService(); } }这里AutoConfiguration默认已经带上了proxyBeanMethods false所以不需要再重复写Configuration。如果你用了Spring Boot 2.7及以上版本这个改写是推荐做法如果还在2.6及以下AutoConfiguration注解还不存在需要根据目标版本决定是否调整。第三步删除spring.factories里的EnableAutoConfiguration条目。如果你的spring.factories还有其他key保留文件和其余内容只删自动配置那一行即可。迁移完成后用--debug启动应用日志里能看到SimpleServiceAutoConfiguration出现在Positive matches中说明新机制生效。3.4 配置类注解的同步更新AutoConfiguration的正确用法很多人在迁移时只改了文件类上的注解没动这种情况在Spring Boot 2.7里不会出错因为Configuration配置类也照样能被.imports加载。但如果你想吃到新机制的全部红利尤其是顺序声明就应该把类上的AutoConfigureBefore、AutoConfigureAfter挪进AutoConfiguration的属性里。原来这样写Configuration(proxyBeanMethods false) AutoConfigureAfter(DataSourceAutoConfiguration.class) public class SimpleRepositoryAutoConfiguration { }新写法AutoConfiguration(after DataSourceAutoConfiguration.class) public class SimpleRepositoryAutoConfiguration { }顺序属性支持类和字符串两种方式比如after com.example.DataSourceAutoConfiguration。如果你要在两个自定义配置类之间控制顺序直接写对方的Class对象即可。注意Spring Boot 2.7开始明确建议不要在同一类上同时使用AutoConfiguration和AutoConfigureBefore/AutoConfigureAfter因为AutoConfiguration本身已经包含了这两个注解的语义重复叠加反而会产生歧义。如果你在代码里看到这种组合统一收敛到AutoConfiguration的属性里。4. 迁移后容易踩坑的四个细节4.1 条件评估日志配置不生效时的第一步排查迁移后最常见的现象是.imports文件建好了类也写了注解但功能就是没生效。最开始我怀疑是文件路径写错后来发现真正的原因是某个ConditionalOnProperty没有匹配上。Spring Boot的自动配置是“候选条件判断”两个阶段类进了候选名单并不代表一定会生效。这时候不要猜直接开条件评估日志两种方式任选启动参数加--debug或者配置logging.level.org.springframework.boot.autoconfigureDEBUG启动后日志里会打印出一段条件评估报告包含所有自动配置候选类的匹配结果Positive matches条件满足配置将要执行Negative matches条件不满足并明确写出了失败原因比如某个类不存在、某个属性缺失、ConditionalOnMissingBean已有其他实例。对照Negative matches里自己配置类的名字基本一眼就能定位问题。这套排查思路适用于任何spring.factories或.imports注册的自动配置类不区分新旧机制。如果是做单元测试更推荐直接使用ApplicationContextRunner来验证配置类的行为不需要启动整个Spring Boot应用new ApplicationContextRunner() .withConfiguration(UserConfigurations.of(SimpleServiceAutoConfiguration.class)) .withPropertyValues(simple.enabledtrue) .run(context - { assertThat(context).hasSingleBean(SimpleService.class); });4.2 顺序控制before/after为什么在新机制下更关键自动配置类之间经常有依赖关系比如你的starter需要用到数据源或者需要在某个官方自动配置执行之后再执行。以前在spring.factories里自动配置的顺序主要靠类上的AutoConfigureBefore和AutoConfigureAfter控制而Spring Boot内部在收集候选配置时还会按类名排序整体顺序其实不难管理。切换新文件后顺序逻辑没有变但它被明确收敛到了AutoConfiguration注解上。建议所有顺序声明都统一用AutoConfiguration的before、after属性这样读代码的人打开类就能看到依赖关系不用再去翻spring.factories猜测顺序。举一个实际例子如果你的自动配置必须晚于DataSourceAutoConfiguration执行AutoConfiguration(after DataSourceAutoConfiguration.class) ConditionalOnClass(DataSource.class) public class MyDatabaseAutoConfiguration { Bean ConditionalOnMissingBean public MyDatabaseHealthIndicator myDatabaseHealthIndicator() { return new MyDatabaseHealthIndicator(); } }这里after声明保证了自己在数据源自动配置完成后才注册Bean避免出现DataSource还不存在时就去判断ConditionalOnBean(DataSource.class)的尴尬。4.3 千万别把“非自动配置”搬进imports迁移过程中最容易犯的错误是抱着“反正都迁移就全搬过去”的心态。前面表格已经列过哪些key不能动我这里再补充一个真实案例。某个内部模块的工具包在spring.factories里注册了一个EnvironmentPostProcessor用来在环境准备阶段修改某些配置属性。维护的同学顺手也把它写进了.imports文件结果Spring Boot启动时直接不认这个处理器环境准备阶段的行为完全缺失而且没有任何异常抛出来只有功能表现不对。原因是.imports只服务于自动配置候选类而EnvironmentPostProcessor的加载逻辑走的是SpringFactoriesLoader两者是独立的扩展机制。它俩连“从同一个文件读取”的路径都不一样自然不是“搬个家”就能解决的问题。所以迁移的准则只有一条自动配置相关的条目才往.imports里放其他扩展点继续留在spring.factories。同一个工程里这两个文件完全可以共存只是职责不同。4.4 多模块、多jar重复注册时的去重问题多模块项目里两个模块的spring.factories可能同时声明了同一个自动配置类。在旧机制下Spring Boot读取时会统一合并然后用LinkedHashSet去重重复类只会执行一次问题不大。切到新机制后情况也类似如果两个jar包里的.imports文件都包含同一个类名最终候选类列表依然会去重。但这里有一个新出现的坑同一个类名在多个jar里出现但类全限定名一致、类内容却来自不同版本这种冲突在合并阶段并不会立刻暴露而是在类加载阶段才真正出错。排查方式也简单查加载时用的是哪个jar包里的类然后检查依赖树里是否有两个版本的jar并存。Maven可以用dependency:treeGradle用dependencyInsight。再补充一个细节在Spring Boot 2.7中如果同一个自动配置类既出现在spring.factories里又出现在.imports里读取时会合并并去重最终只保留一份不会执行两次。但如果两边写的类名大小写不一致或者混入了空格导致字符串不相同就会留下两个不同候选这个问题排查起来非常隐蔽。因此迁移时我建议一次性把spring.factories里的旧条目删干净不要留两边并存的中间状态。5. 版本兼容与长期维护给自定义starter定一份稳妥的配置策略5.1 不同版本下的兼容方案怎么选如果你维护的自定义starter需要被多个项目使用最头疼的问题就是别人用Spring Boot 2.6你用新机制他的项目读不到别人用3.0你只写旧文件他的配置又静默失效。不同目标版本对应的推荐方案可以这样列目标Spring Boot版本推荐做法2.3 ~ 2.6只能使用spring.factories2.7 ~ 2.7.18优先使用AutoConfiguration.imports旧文件可作兜底3.0 及以上必须使用AutoConfiguration.imports如果你的库要同时兼容2.6和3.0最直接的做法是同时保留两个文件spring.factories里仍保留EnableAutoConfiguration条目.imports文件也建好。这样2.6项目读旧文件3.0项目读新文件2.7项目两者都会读到。这里有个前置条件容易忽略Spring Boot 3.0要求Java 17及以上而2.6通常跑在Java 8或Java 11上。如果你用一个Java 17编译的jar包去兼容Java 8运行时类版本都会报错更别提自动配置机制了。所以真正的跨大版本兼容实践中往往是分成两条发布线而不是靠一个jar通吃。2.6及以下版本走旧分支3.x走新分支二者各自维护。这种“一个jar两文件”的方式只用于同一Java基础版本下的小版本兼容。5.2 最容易出现的“假成功”文件建了但版本不支持某次我把一个自定义starter的自动配置全部迁到了.imports文件本地测试用的Spring Boot是2.7跑得好好的。后来把同一份jar丢给一个还在用Spring Boot 2.6的项目对方反馈功能没生效。一开始我以为对方漏配了EnableAutoConfiguration或者引入依赖不完整后来检查才发现原因很简单Spring Boot 2.6根本不认识AutoConfiguration.imports这个机制。它不会报错也不会给你任何提示就像新文件不存在一样。如果没有在对应版本上跑冒烟测试这类问题几乎不可能第一时间发现。所以我的建议是无论你怎么选发布前必须准备一份针对目标版本的自动化冒烟测试至少包含一个带条件注解的配置类和一个简单的功能验证。尤其是自定义starter这种被多个项目引用的基础组件版本兼容不能靠口头承诺。5.3 自定义starter的最终配置检查清单结合上面的迁移实践我整理了一份检查清单每次新建或升级自定义starter时都会过一遍所有自动配置类的全限定名是否逐行写在META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports中配置类是否使用了AutoConfiguration注解而不是旧式Configuration顺序控制是否统一放在AutoConfiguration的before、after属性中spring.factories里是否还有残留的EnableAutoConfiguration条目spring.factories中其他扩展点如EnvironmentPostProcessor、ApplicationContextInitializer是否原样保留是否用ApplicationContextRunner或者--debug验证过条件评估结果是否在最低支持的Spring Boot版本上跑过测试打包产物里是否真的包含了.imports文件解压jar tf确认路径完整。这套清单用过几次之后基本能保证自动配置机制的迁移不再出现低级问题。结合我自己的实际维护经验最后想多说一句新建自定义starter时我现在的习惯是第一步就把.imports文件建好配置类直接写AutoConfiguration从一开始就站在新机制这侧。原因很简单新项目大概率都是2.7或3.x起步早切早安心。如果你还在维护一个老库最稳妥的方式是两个文件并存spring.factories兜底老版本.imports面向新版本。这是我先后迁移了多个内部组件后得出的结论版本兼容这件事永远不要指望使用者帮你适配而是在设计阶段就替他们想好。