这里有一点需要先说明你提供的 URL 包含一个用户输入问题但中间夹杂了“返回prompt以开始新对话”这类无关信息这里按常规方式直接写这篇 Spring Boot 的博文。1. 这个文件到底在解决什么问题Spring Boot 为什么非要有 spring.factories很多人在初次接触 Spring Boot 时会觉得它像变魔术一样写一个带SpringBootApplication的启动类项目就能自动扫到一堆配置类数据库连接池、Redis、消息队列全部自动配置好甚至第三方封装的组件也能在 jar 包被引入后自动生效。你明明没有Import它也没有在启动类里ComponentScan指定那个包的路径它到底是怎么被发现的答案的关键就是META-INF/spring.factories。这个文件的本质是 Spring Boot 留给外部 jar 包的一个“接入声明”。它遵循 Java 的 SPIService Provider Interface思想不是由启动项目主动去扫描某个特定包下的实现类而是由各个 jar 包自己把自己要暴露给外面的扩展点写进一个固定位置的文件里Spring Boot 启动时统一去加载这些文件把里面声明的类名一个个捞出来。你可以拿它跟生活中的插线板做类比spring.factories就像设备包装盒里自带的那张“接口规格说明卡”。你买了一个智能音箱它附赠一张卡片写着“请将电源插头插入 220V 电源插座”Spring Boot 就是那个标准的电源插座它不需要知道世界上有多少种设备只要设备厂商按规定把卡片上的信息写好插上就能工作。这里我会特别提醒一个容易混淆的点很多初学者以为spring.factories只是“自动配置”的入口实际上它管的事比这宽得多。它还能注册ApplicationContextInitializer、ApplicationListener、EnvironmentPostProcessor、FailureAnalyzer等一大票扩展点。也就是说凡是需要 Spring Boot 在启动早期“照着名单来找我”的功能几乎都可以通过这个文件暴露。后面我会逐个展开。另外一个容易造成理解偏差的地方是spring.factories里的类名之所以能生效是因为 Spring Boot 在启动时用SpringFactoriesLoader统一加载了 classpath 下所有 jar 包里的这个文件而不是 Spring 容器本身在扫描什么。这个加载动作发生在 Spring 容器刷新之前甚至在BeanFactory还没完全准备好的阶段就已经开始了。所以它承载的不是普通 bean 注册逻辑而是框架层面的启动扩展机制。理解这层背景之后你再去看网上那些“把Configuration写在第三方 jar 里但就是不生效”的报错会发现绝大多数原因都一样你只是把配置类写在了 jar 包里但没有在spring.factories里声明它Spring Boot 根本不知道你的配置类存在自然也就谈不上加载。这是使用这个机制之前必须先建立的认知。2. 从源码视角拆解加载链路SpringFactoriesLoader 和自动配置装配的底牌光知道“插线板”还不够我建议你把源码翻一遍搞懂spring.factories到底是怎么被读出来的。这里我会用 Spring Boot 2.x 系列的源码做说明因为目前生产环境用量最大的还是 2.3.x、2.6.x 和 2.7.x。你要打开两个类就够用org.springframework.core.io.support.SpringFactoriesLoader和org.springframework.boot.autoconfigure.AutoConfigurationImportSelector。2.1 SpringFactoriesLoader这个加载器其实可以当成一套独立 API 来用核心方法就是loadFactories和loadFactoryNames底层逻辑可以概括成三步在 classpath 下找所有META-INF/spring.factories文件解析每个文件里的配置按接口/注解全限定名 实现类1,实现类2的格式组织成一个 Map调用方根据自己的需求拿出 key 对应的 value 列表再通过反射实例化或交给容器处理。我用一段伪代码帮大家回忆一下底层结构// spring-core 里类路径下所有 spring.factories 会被合并成一个 Properties 对象 // 比如 // org.springframework.boot.autoconfigure.EnableAutoConfiguration\ // com.example.autoconfigure.MyAutoConfiguration,\ // com.example.autoconfigure.OtherAutoConfiguration public final class SpringFactoriesLoader { public static final String FACTORIES_RESOURCE_LOCATION META-INF/spring.factories; // 加载所有 jar 包里这个路径下的资源汇总 key-value }注意这里面的一个关键细节多个 jar 包里如果存在同名META-INF/spring.factoriesSpring 会通过PropertiesLoaderUtils把它们全部读出来并合并不是只取第一个。如果你接手过大型多模块项目排查“明明我这个 jar 包里有配置类但启动日志里根本没加载”的问题时多半就是合并过程中出了幺蛾子常见情况包括文件内容被截断、格式写错、编码不对。这些我放到第 5 章专门讲。2.2 EnableAutoConfiguration 加载链路从注解到条件装配我们平时接触最多的自动配置入口是EnableAutoConfiguration这其实就是一个聚合注解。启动类上的SpringBootApplication包含了它所以启动项目时自动配置引擎就会被激活。下面是关键链路我按时序梳理出来SpringBootApplication被解析触发EnableAutoConfigurationImportSelector如果是 2.7 之后叫AutoConfigurationImportSelector这个 selector 调用SpringFactoriesLoader.loadFactoryNames(EnableAutoConfiguration.class, classLoader)从所有 jar 包的spring.factories里拿出EnableAutoConfigurationkey 下配置的所有类名这些类名会被当成候选自动配置类随后进入ConditionEvaluator逐个判断类上的ConditionalOnClass、ConditionalOnMissingBean、ConditionalOnProperty等条件注解是否满足条件满足的配置类才会被注册到容器中不满足的直接跳过。这里就解释了一个经典问题为什么我的 jar 包里声明了自动配置类但类里定义的那些 bean 没生效因为Configuration只是让你“有资格”成为一个配置类真正决定 bean 是否能被注册的是类上那一堆ConditionalOn*条件。比如你引入了一个封装 Paypal 支付的 starter但项目里没有PaypalClient这个类条件不成立Spring Boot 会假装这个自动配置类不存在。这是整个自动配置机制里最重要的设计它让 Spring Boot 能做到“引入 jar 就生效、不引入就不报错”。2.3 为什么 Spring Boot 放弃直接扫描第三方包一个关于可控性的取舍有人会问为什么不直接在启动类上做整体包扫描把 starter 所在的包路径也扫进去那样不就省掉spring.factories这一步了这里要理解 Spring Boot 的一个设计原则第三方 jar 包里的 bean 不应该无条件注册到你的容器里。如果直接扫描意味着你引入任何一个 starter 就会把它内部所有Component、Configuration、Service全部装载哪怕里面很多东西你用不上。这会带来两个问题启动时间被拉长你无法通过配置开关控制哪些功能生效。而spring.factories配合条件注解本质上把注册权从“包扫描”这种粗粒度方式收回到“按需声明 条件判断”这种细粒度方式。从实际经验看这也是排查故障时最容易出问题的分界线你以为自动配置是“扫到就能用”实际上它是“声明才可能被加载条件满足才会注册”。这两个阶段是独立的忘记了就不会生效。3. 实操自己写一个 starter把 spring.factories 跑通概念说得再多也不如直接写一个能跑的例子。我带大家实现一个最简版的自定义 starter一个把系统 CPU 核心数和 JVM 内存信息暴露成 bean 的SystemInfoAutoConfiguration。麻雀虽小但spring.factories、条件注解、ConfigurationProperties 都会用到。3.1 工程结构与配置类我先建一个普通 Maven 工程system-info-spring-boot-starter依赖只给spring-boot-autoconfigure就够了不需要把spring-boot-starter整个引入。这个细节我后面会解释原因。核心配置类代码如下package com.example.systeminfo; import org.springframework.boot.autoconfigure.condition.ConditionalOnClass; import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean; import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; import org.springframework.boot.context.properties.EnableConfigurationProperties; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; Configuration ConditionalOnClass(org.springframework.core.env.Environment.class) EnableConfigurationProperties(SystemInfoProperties.class) public class SystemInfoAutoConfiguration { Bean ConditionalOnMissingBean public SystemInfoService systemInfoService() { return new SystemInfoService(Runtime.getRuntime().availableProcessors(), Runtime.getRuntime().maxMemory() / 1024 / 1024); } }这段代码里我故意保留了几个值得琢磨的细节ConditionalOnClass(Environment.class)其实没有实际过滤作用因为任何 Spring Boot 项目都有这个类但它演示了条件注解的写法ConditionalOnMissingBean保证用户自己声明了SystemInfoService的实例时自动配置不会强行覆盖EnableConfigurationProperties把属性绑定类激活这样用户可以通过application.properties配置自定义项。3.2 spring.factories 文件怎么放、怎么写配置文件放到src/main/resources/META-INF/spring.factories下。注意路径是META-INF大写INF漏掉一个字符就白搭。org.springframework.boot.autoconfigure.EnableAutoConfiguration\ com.example.systeminfo.SystemInfoAutoConfiguration如果还想在这个 jar 包里注册一个启动监听器可以在同一个文件里再追加一段org.springframework.context.ApplicationListener\ com.example.systeminfo.SystemInfoApplicationListenerApplicationListener这个 key 对应的值是org.springframework.context.ApplicationListener的完全限定名。Spring Boot 启动早期会通过 key 来找到它并实例化这也是spring.factories不局限于自动配置的实证。3.3 把 starter 配置进项目并验证在业务项目里引入 starterdependency groupIdcom.example/groupId artifactIdsystem-info-spring-boot-starter/artifactId version1.0.0/version /dependency然后在启动类或者任意一个Configuration里注入测试Component public class SystemInfoPrinter { private final SystemInfoService systemInfoService; public SystemInfoPrinter(SystemInfoService systemInfoService) { this.systemInfoService systemInfoService; System.out.println(可用处理器: systemInfoService.getAvailableProcessors()); System.out.println(最大内存: systemInfoService.getMaxMemoryMb() MB); } }启动项目看到控制台输出这两行你的 starter 就跑通了。如果把依赖注释掉项目启动完全不受影响这就是条件装配的魅力。这里我额外强调一个项目实践starter 工程本身不要引入spring-boot-starter只引入spring-boot-autoconfigure即可否则你会把一大堆默认依赖传导给业务项目。我之前见过一个团队把spring-boot-starter-web写进自己的 starter 里结果所有下层服务被迫带上了 Web 容器端口冲突问题排查了半天。控制依赖范围是写 starter 的第一生存法则。4. 从 2.7 到 3.0spring.factories 的迁移与新的自动配置声明如果你准备升级 Spring Boot或者正在维护老项目迁移下面这段值得仔细看因为它解决的是“为什么我在 Spring Boot 3 里配了spring.factories但自动配置就是不生效”的高频问题。4.1 官方迁移的背景spring.factories 为什么不够用了Spring Boot 团队在 2.7 版本引入了一套新机制META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports。在 3.0 之后老式的自动配置 keyorg.springframework.boot.autoconfigure.EnableAutoConfiguration从spring.factories里彻底移除不再被加载。为什么会有这个变化官方 release note 里提到的原因主要包含三点spring.factories用一个 Properties 格式承载多种 key但其中的自动配置 key 在启动阶段需要被优先读取其他扩展点则是按需读取统一塞在一个文件里不利于框架分类加载properties 格式对 IDE 不友好写起来容易出错特别是转义字符为了配合 Spring Boot 3 基于 Spring Framework 6 的底层重构自动配置加载路径希望更清晰。这个变化背后的核心逻辑是把“自动配置”从spring.factories这个大筐里单独拎出来给它们一个专属的 imports 文件。但你要注意其余扩展点比如ApplicationListener、EnvironmentPostProcessor、FailureAnalyzer在 2.7 和 3.0 里依然保持使用spring.factories。所以正确的说法不是“spring.factories 没了”而是“自动配置的声明方式变了”。4.2 新旧写法对照清单为了方便大家对照迁移我做了一张常用配置的对照表扩展点2.7 之前含 2.62.7 3.0 迁移后自动配置类spring.factories里用EnableAutoConfigurationkeyMETA-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports每行一个类名ApplicationListenerspring.factories里用ApplicationListenerkey保持不变仍用spring.factoriesEnvironmentPostProcessorspring.factories里用EnvironmentPostProcessorkey保持不变仍用spring.factoriesFailureAnalyzerspring.factories里用FailureAnalyzerkey保持不变仍用spring.factoriesApplicationContextInitializerspring.factories里用ApplicationContextInitializerkey保持不变仍用spring.factories迁移动作本身不复杂// META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports // 注意这个文件是 UTF-8 编码一行一个类名千万别写逗号分隔 com.example.systeminfo.SystemInfoAutoConfiguration com.example.systeminfo.OtherAutoConfiguration这里要吐槽一个常见的坑很多从 2.x 迁移上来的同学会习惯性地把多个类名用逗号分隔写得跟原来 properties 一样结果启动时直接报找不到自动配置类或者只加载了第一个。这个文件的解析方式是逐行读取不是按逗号分割。我建议你迁移后第一件事就是打开这个 imports 文件确认每一行只有一个类名并且没有尾随空格。另外还有一个细节Spring Boot 2.7 里两类文件是被同时支持的。也就是说你可以在spring.factories里保留老的自动配置 key也可以把新写的自动配置类放进 imports 文件。但到了 3.0spring.factories里那个 key 就完全失效了。所以如果你打算用 Spring Boot 3老项目的自动配置声明必须搬过去。4.3 优先级和重复声明的处理在 2.7 过渡期如果同一个自动配置类在新旧两个文件里都被声明了怎么办实测下来的结果是会被当成两条记录加载可能导致配置类被评估两次。大多数情况下因为ConditionalOnMissingBean的存在最终只会注册一次 bean但重复加载会影响启动时间同时会让排查日志显得混乱。所以迁移时最好全项目搜一下EnableAutoConfiguration这个 key把所有自动配置声明一次性搬干净不要新旧混着来。5. 实战中的坑格式、合并、顺序与条件解析我把测试过的弯路都列出来这一章来自实际项目中的多次踩坑记录。网上对spring.factories的讲解往往只到“写个文件就能用”但在真实的大型项目里问题往往出在文件合并、加载顺序、条件评估这些阴暗的角落。5.1 多 Module 工程里 spring.factories 文件冲突问题在一个聚合工程里爸爸模块依赖子模块 A子模块 B 又依赖子模块 A每个模块自己都带一个META-INF/spring.factories。如果不同模块的这个文件里声明了同 key 的配置类原则上会被合并加载不会冲突。真正出问题的是另一种情况文件里不小心写了中文字符或签名号导致解析时出现UncheckedIOException启动直接崩。另外要注意构建工具的坑如果用 Maven 做多模块打包某个子模块的spring.factories文件被意外过滤掉了最常见的诱因是pom.xml里配置了resources过滤并且没有把**/*.factories和**/*.imports放进去。这种问题非常隐蔽因为项目在 IDEA 里直接跑正常一打正式包就丢文件。解决办法打包后打开 jar 包用以下命令检查 resources 里是否存在这两个文件jar tf target/system-info-spring-boot-starter-1.0.0.jar | grep -E spring.factories|AutoConfiguration.imports5.2 加载顺序AutoConfigureBefore、AutoConfigureAfter 到底怎么用自动配置类的加载顺序不是由spring.factories里的声明顺序决定的。Spring Boot 在评估自动配置类时会先收集全部候选清单然后排序接着再逐个做条件判断。排序规则由三个维度控制AutoConfigureOrder注解、AutoConfigureBefore、AutoConfigureAfter注解以及 properties 文件里的spring.autoconfigure.exclude排除项。最常见的需求场景是你写了一个RedisAutoConfiguration的增强配置类需要判断在 Redis 的默认自动配置生效之后再去注册自己的 bean。正确写法是Configuration AutoConfigureAfter(RedisAutoConfiguration.class) public class MyRedisEnhancerAutoConfiguration { // 你的增强逻辑 }这里有个我自己用过的排查技巧启动时加参数开启条件评估报告看你的配置类被跳过或被加载的原因--debug启动日志会输出一份正反条件的匹配报告罗列每个自动配置类为什么生效、为什么不生效。那个报告在排查顺序问题或条件不满足问题的时候远比看源码快。5.3 Configuration 与 ConditionalOnClass 的经典“半天不生效”问题一个很容易被忽略的坑ConditionalOnClass如果没有指定name属性那么类加载时机发生在 auto-configuration 类被解析的阶段。如果你的配置类里通过静态方法引用了第三方类而这个类不在 classpath 中JVM 可能在加载配置类本身时就会抛出NoClassDefFoundError而不是简单地让条件不成立。正确做法在自动配置类的条件注解上尽量用字符串形式指定类名Configuration ConditionalOnClass(name com.paypal.api.payments.Payment) public class PaypalAutoConfiguration { // 只会校验字符串不触发类加载安全 }用ConditionalOnClass(Payment.class)值方式在编译器会检查那个类是否存在从而导致 jar 包在缺少该依赖时启动报错。这种错误是“写了但还没到条件判断阶段就已经崩了”体现为非常奇怪的类加载异常。看了这份经验你应该明白为什么 Spring Boot 官方推荐优先用name属性其次才用value属性。5.4 使用父项目聚合时对 imports 文件的编码要求AutoConfiguration.imports文件对编码的处理比spring.factories更敏感。Maven 打包时如果统一把源码编码设为 GBK 或系统默认编码而 IDE 里是 UTF-8文件内容里的类名没问题但如果有注释或空行带着不可见字符在类名解析阶段就会出现IllegalArgumentException: Failed to load auto-configurations。我的建议是在所有 Maven 工程里显式声明project.build.sourceEncodingUTF-8如果已经出问题用十六进制或文本编辑器确认 imports 文件确实是 UTF-8 无 BOM 编码。加了 BOM 的文件在解析第一行时往往会带上不可见字符导致后面整行类名打不出来。5.5 多个 starter 之间互相依赖的循环加载写过内部公共 starter 的人可能遇过这个场景A starter 的自动配置类需要读取 B starter 里的某个 bean而 B starter 又依赖 A starter 的某个 bean。由于自动配置类只是“候选类”它们的加载顺序看注解但 bean 实例化的依赖关系可能在Bean方法参数层面体现。如果排序不对就会有 NoSuchBeanDefinitionException。处理这类问题有几个备选方案我按推荐顺序列一下拆分配置类把 A、B 两者需要互相依赖的部分抽成独立的C配置类通过在 imports 文件里调整行顺序虽然官方不承诺行顺序即加载顺序但实测中 imports 文件的行序在排序后的初始列表里确实会影响默认优先级使用ObjectProviderT或ApplicationContext延迟获取显式用AutoConfigureOrder指定顺序。特别提醒AutoConfiguration.imports的行顺序不是标准文档承诺的排序依据不要过度依赖它。真正可靠的手段还是注解和顺序接口。6. 进阶玩法用 spring.factories 做故障分析器和环境后处理器介绍完常规套路我再分享两个实战中不怎么被提起、但非常好用的功能扩展点。它们同样藏在spring.factories里属于“不想写死在启动类里、但需要全局介入”的场景。6.1 自定义 FailureAnalyzer报错信息变得可读默认情况下Spring Boot 启动报错时你会看到一长串堆栈。借助FailureAnalyzer你可以捕获特定异常并输出一段“人话”提示比如明确告诉运维“你少配了某个 key或某个依赖版本过低”。写法非常简单public class MissingRedisPasswordFailureAnalyzer extends AbstractFailureAnalyzerRedisConnectionFailureException { Override protected FailureAnalysis analyze(Throwable rootFailure, RedisConnectionFailureException cause) { return new FailureAnalysis( 连接 Redis 时出现密码错误或未配置密码, 请在 application.properties 中配置 spring.data.redis.password, cause ); } }然后在spring.factories里注册org.springframework.boot.diagnostics.FailureAnalyzer\ com.example.systeminfo.MissingRedisPasswordFailureAnalyzer这种做法的好处是故障信息直接面向使用者不用人人去看堆栈。内部 starter 提供给多个业务团队的时候这个能力特别值得做。6.2 定制 EnvironmentPostProcessor在配置加载前干预环境另一个常被忽略的点是EnvironmentPostProcessor。它在 Spring 环境准备阶段执行容器 bean 都还没创建。你可以在这一步动态往环境中注入属性或调整配置源优先级。比如做一个“根据部署环境自动切换配置中心”的 starterpublic class CustomConfigCenterEnvironmentPostProcessor implements EnvironmentPostProcessor { Override public void postProcessEnvironment(ConfigurableEnvironment environment, SpringApplication application) { String active environment.getProperty(spring.profiles.active, dev); // 按不同环境把不同的配置源塞进 environment } }注册进spring.factoriesorg.springframework.boot.env.EnvironmentPostProcessor\ com.example.systeminfo.CustomConfigCenterEnvironmentPostProcessor这里有个坑EnvironmentPostProcessor的加载早于日志系统初始化如果你在实现类里写日志依赖可能出现启动早期日志不输出的情况。最佳实践是在这个阶段用System.out或直接抛异常来暴露问题千万别依赖 logback。7. 十几份 spring.factories 之后的个人总结写了几年 Spring Boot各种花样的 starter 也维护过不少说几个个人体会供参考。第一spring.factories不是“配置文件”它更像是 jar 包对 Spring Boot 容器的服务清单。结构极其简单但产生问题的位置往往不在文件本身而在解析时机、加载顺序和条件判断的相互配合中。第二2.7 之后自动配置声明迁移到AutoConfiguration.imports不代表你要放弃spring.factories的经验。实际上像监听器、环境后处理器、故障分析器这些扩展点仍然需要写spring.factories。不少人在新项目里把所有东西都想往 imports 文件里塞这是不对的。第三排查“自动配置没生效”的问题我建议按这个顺序走先检查 jar 包里的文件是否被打包进去再确认写法是旧的EnableAutoConfigurationkey 还是新的 imports 文件开启--debug看条件评估报告最后才去分析条件注解和顺序。第四建议团队内部把spring.factories的维护规范定下来包括禁止在文件里写非 ASCII 字符所有类名必须带包名全限定自动配置类路径统一放在xx.xx.autoconfigure包下新增配置必须配有ConditionalOn****条件。这些细节能在多模块、多团队协作时省下大量扯皮时间。简单一个文件背负的却是整个 Spring Boot 自动配置体系的入口。把它的加载机制和边界条件搞清楚了写 starter、排查启动问题、做框架集成都会顺手很多。希望这篇总结能帮到正在和 Spring Boot 较劲的你。