Spring Boot 的自动配置（AutoConfiguration）是它最讨喜的特性之一，但也是很多人在项目里跟它斗智斗勇的地方。默认情况下，只要类路径里有对应的依赖，Spring Boot 就替你装配好一大堆 Bean，省事是真省事，可一旦遇到多数据源、版本冲突、或者你只想用自己那套初始化逻辑时，它反而会好心办坏事。这篇博客就专门聊一个话题：Spring Boot 的自动配置到底该怎么排除，以及排除了之后怎么把窟窿补上。我会从原理讲起，再给你几段可以直接抄走的实操配置，最后把我踩过的一些坑都列出来，适合正在被自动配置干扰、或者想彻底掌控 Bean 装配逻辑的开发者参考。
1. 自动配置背后到底发生了什么
1.1 自动配置的三个关键机制
想要把"排除"这件事做明白，先得搞清楚自动配置是怎么生效的。在 Spring Boot 2.7 之前，自动配置类是通过META-INF/spring.factories文件里的一行org.springframework.boot.autoconfigure.EnableAutoConfiguration键来声明的；到了 Boot 2.7 之后，引入了一个更清晰的文件：META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports，每一行写一个自动配置类的全限定名。Spring Boot 在启动时会扫描这些文件，把候选的自动配置类全部加载进来。
接下来是条件判断。自动配置类上通常叠加了@ConditionalOnClass、@ConditionalOnMissingBean、@ConditionalOnProperty这一系列注解。@ConditionalOnClass看的是类路径上有没有指定的类，如果没有，整个配置类直接跳过；@ConditionalOnMissingBean看的是容器里有没有对应类型的 Bean，如果你已经手动定义过，自动配置就不再生效；@ConditionalOnProperty则看配置项是否满足预期值。这三层条件组合在一起，决定了哪些 Beaan 会被真正创建。
最后是生效后的装配。比如DataSourceAutoConfiguration里会根据你配置的数据库连接信息，调用DataSourceProperties去构建一个HikariDataSource。整个链路从 "加载候选类" 到 "条件匹配" 再到 "创建 Bean"，环环相扣。搞清楚这个链路，你再去看排除逻辑就容易多了：排除本质上就是在第一步或者条件匹配阶段干预它，让某些自动配置类根本不进入候选集合，或者让它的条件不再满足。
1.2 什么时候你会真正需要"排除"自动配置
有人可能会问：既然自动配置这么智能，为什么还要手动排除？我总结了几个高频场景，碰到任意一个，你就该考虑干预了。
第一是依赖冲突。类路径里刚好有多个库实现了同一类功能，比如同时引入了 H2 和 MySQL 驱动，Spring Boot 可能根据配置自动选了一个，但实际想用的是另一个。第二是定制化需求。自动配置创建的 Bean 往往是最简版本，比如它默认创建的RedisTemplate使用 JDK 序列化，你希望改成 Jackson 序列化，与其改完再覆盖，不如直接排除它的RedisAutoConfiguration，只保留自己手写的配置类。第三是启动效率问题。有些自动配置类即使条件不满足，也会在启动阶段做大量类扫描和反射操作，比如调试时发现启动日志里频繁出现某些你根本用不到的库的初始化过程，排除掉可以减少启动时间。第四是特殊环境的兼容问题，比如某些类库和你的框架版本不兼容，自动配置初始化时报错，此时你会想先把它的自动配置关掉，再用手动方式绕过问题。
我自己的经验是：能通过@ConditionalOnMissingBean和配置项解决的，尽量不要动用"排除"这把大锤，毕竟自动配置在绝大多数时候是经过充分测试的。只有在手动定义 Bean 仍然兜不住、或者自动配置类本身就有 bug 的罕见情况下，才需要把整个自动配置类排除掉。
2. 四种排除手段怎么选
2.1 注解排除：@SpringBootApplication 与 @EnableAutoConfiguration
最常见的排除方式是直接在启动类上用注解属性。如果你用的是@SpringBootApplication，可以直接写：
@SpringBootApplication(exclude = { DataSourceAutoConfiguration.class, RedisAutoConfiguration.class }) public class DemoApplication { public static void main(String[] args) { SpringApplication.run(DemoApplication.class, args); } }如果你没有用@SpringBootApplication，而是手动组合了@Configuration、@EnableAutoConfiguration、@ComponentScan，那就在@EnableAutoConfiguration上写同样的 exclude 属性：
@Configuration @EnableAutoConfiguration(exclude = DataSourceAutoConfiguration.class) @ComponentScan(basePackages = "com.example.demo") public class AppConfig { }@SpringBootApplication本质上是这三者的组合注解，所以两种写法等价。注意exclude接收的是Class<?>[]，你必须引用到具体的自动配置类。如果有些自动配置类的类名太长，比如org.springframework.boot.autoconfigure.mongo.MongoAutoConfiguration，我还建议用excludeName属性，直接传字符串：
@SpringBootApplication(excludeName = { "org.springframework.boot.autoconfigure.mongo.MongoAutoConfiguration" })字符串的好处是，某些极端场景下编译期类路径里可能压根没有这个类，用 Class 引用会导致编译失败，用excludeName可以避开编译依赖。
2.2 配置驱动：spring.autoconfigure.exclude
注解排除虽然直观，但它写死在代码里，不利于在不同环境切换。Spring Boot 还提供了一种纯配置的排除方式，放在application.yml或者application.properties里：
spring: autoconfigure: exclude: - org.springframework.boot.autoconfigure.data.redis.RedisAutoConfiguration - org.springframework.boot.autoconfigure.kafka.KafkaAutoConfigurationproperties 写法则是：
spring.autoconfigure.exclude=org.springframework.boot.autoconfigure.data.redis.RedisAutoConfiguration,\ org.springframework.boot.autoconfigure.kafka.KafkaAutoConfiguration配置文件方式的优点是灵活，一个项目在不同环境可以加载不同的配置文件，排除项也随之变化。它还支持数组形式，排除多个类时不用在代码里维护一长串exclude属性。但我需要提醒一句：这种方式的坑在于配置项拼写容易错，特别是逗号、换行、空格处理不当，导致某一个自动配置类没被排除。尤其是 YAML 的换行风格有时候会让你误以为每个类单独一行，实际上解析出问题很难一眼看出来。
2.3 条件注解的"软排除"
严格来说，@ConditionalOnProperty这类条件注解并不是"排除"，但它能达到类似效果。例如某个第三方库的自动配置类上写了：
@ConditionalOnProperty(name = "myapp.feature.enabled", havingValue = "true")如果你在配置里不设置这个属性，自动配置就自动失效。这种方式的好处是不用知道自动配置类的全限定名，通过配置就能控制。问题是，它依赖库的作者是否预留了开关，很多自动配置类根本没有这种设计，你能做的很有限。
还有一种软排除思路是抢在自动配置之前定义自己的 Bean。因为大量自动配置类依赖@ConditionalOnMissingBean，当你手动声明了一个同类型 Bean 时，自动配置的整个分支都会被跳过。比如你自定义了一个DataSource，那DataSourceAutoConfiguration内部创建数据源的部分就不会执行。这种方式的坏处是：它可能只是"跳过 Bean 创建"，自动配置类仍会被加载、条件判断仍然执行，有时候侧边效应还是存在。
2.4 四种方式的优先级对比
我把这几种方式放在一起对比一下，方便你在实际项目里做选择：
| 排除方式 | 作用域 | 灵活度 | 适合场景 |
|---|---|---|---|
@SpringBootApplication(exclude=...) | 启动类 | 中 | 全局统一排除，代码里一眼可见 |
@EnableAutoConfiguration(exclude=...) | 启动类/配置类 | 中 | 没有使用组合注解时 |
spring.autoconfigure.exclude | 配置文件 | 高 | 区分环境、动态调整 |
@ConditionalOnProperty | 由第三方提供 | 高 | 库作者预留了开关 |
| 自定义同类型 Bean | 容器内 | 低 | 只想覆盖实现、不想关掉核心配置 |
如果你问我最推荐哪种，我会说：日常开发优先用spring.autoconfigure.exclude，因为配置和代码分离，排查问题的时候不用去翻启动类。但如果这个排除是项目的硬性要求，任何环境都必须排除，那写在@SpringBootApplication上更直观，防止被某些团队成员的本地配置覆盖。
3. 三个典型场景的排除实操
3.1 排除数据源自动配置，自己掌控 DataSource
先看一个最常见的实战场景：项目里引了 MyBatis、MySQL，但 Spring Boot 启动时报错，说无法确定合适的数据库驱动，或者你根本不需要 Spring Boot 自动创建数据源。如果你在一个模块里同时引了多个数据源依赖，还不想让自动配置帮你选，那直接关掉DataSourceAutoConfiguration最省心。
操作很简单，启动类上加：
@SpringBootApplication(exclude = DataSourceAutoConfiguration.class)此时如果你还用了 JPA、MyBatis 等 ORM 框架，它们相关的自动配置类也可能会因为缺少DataSource而报错，所以通常要连带排除：
@SpringBootApplication(exclude = { DataSourceAutoConfiguration.class, HibernateJpaAutoConfiguration.class, MybatisAutoConfiguration.class })排除了之后，你就得自己手动创建数据源。这里给你一个完整的手写配置示例：
@Configuration public class ManualDataSourceConfig { @Bean @ConfigurationProperties("app.datasource") public DataSourceProperties dataSourceProperties() { return new DataSourceProperties(); } @Bean public DataSource dataSource(DataSourceProperties properties) { return properties.initializeDataSourceBuilder() .type(HikariDataSource.class) .build(); } }对应的 yml 配置：
app: datasource: url: jdbc:mysql://localhost:3306/demo username: root password: secret driver-class-name: com.mysql.cj.jdbc.Driver注意，这里我没有用 Spring Boot 默认的spring.datasource.*前缀，而是换成了app.datasource.*，目的就是彻底摆脱自动配置的关联。你如果还是想用spring.datasource.*前缀，其实也没关系，DataSourceProperties也能绑定，但既然已经排除了自动配置，我还是建议前缀独立命名，语义更清晰。
3.2 排除 Redis 自动配置，定制 RedisTemplate
第二个高频场景是 Redis。Spring Boot 默认的RedisAutoConfiguration会创建一个RedisTemplate<Object, Object>，并且使用 JdkSerializationRedisSerializer，键值对在 Redis 里显示为二进制乱码，调试很不友好。你要是想用 String 序列化或者 Jackson 序列化，最痛快的办法就是排除 Redis 自动配置，自己定义模板。
先排除：
@SpringBootApplication(exclude = RedisAutoConfiguration.class)然后自己写一个配置类：
@Configuration public class RedisConfig { @Bean public RedisTemplate<String, Object> redisTemplate(RedisConnectionFactory factory) { RedisTemplate<String, Object> template = new RedisTemplate<>(); template.setConnectionFactory(factory); StringRedisSerializer keySerializer = new StringRedisSerializer(); GenericJackson2JsonRedisSerializer valueSerializer = new GenericJackson2JsonRedisSerializer(); template.setKeySerializer(keySerializer); template.setHashKeySerializer(keySerializer); template.setValueSerializer(valueSerializer); template.setHashValueSerializer(valueSerializer); template.afterPropertiesSet(); return template; } }这里有个细节：虽然你排除了RedisAutoConfiguration，但RedisConnectionFactory通常还是由LettuceRedisAutoConfiguration或JedisConnectionFactory相关的自动配置创建的，所以只要 classpath 里有对应客户端依赖，连接工厂一般不会缺失。如果你的项目里连连接工厂也想自己管，那还需要把LettuceAutoConfiguration一起排除，再自己定义RedisConnectionFactoryBean。大多数情况下不需要走到这一步，RedisAutoConfiguration的重点是那个模板，连接工厂让它自动创建就好。
用这种方式，你在代码里注入RedisTemplate<String, Object>的时候，拿到的就是完全符合自己序列化需求的对象。这也是我在多个项目里一直采用的玩法，虽然多写了几行配置，但调试时看到 Redis 里的字符串干干净净，完全不踩乱码的坑。
3.3 排除 Kafka 自动配置，避免无谓连接
Kafka 的自动配置同样值得关注。KafkaAutoConfiguration会在你只要引入spring-kafka依赖时就尝试创建KafkaTemplate，但如果你只是用了 Kafka 相关的工具类，或者想在测试环境避免它主动连接 broker，就可以先把它排除掉。
排除方式：
spring: autoconfigure: exclude: - org.springframework.boot.autoconfigure.kafka.KafkaAutoConfiguration你可能会想：那KafkaTemplate怎么办？其实如果只是个别类需要发消息，你可以手动构建一个轻量的KafkaTemplate，指定 producer 配置，而不必让整个 auto-configuration 体系参与进来。例如：
@Configuration public class KafkaManualConfig { @Bean public KafkaTemplate<String, String> kafkaTemplate() { Map<String, Object> props = new HashMap<>(); props.put(ProducerConfig.BOOTSTRAP_SERVERS_CONFIG, "localhost:9092"); props.put(ProducerConfig.KEY_SERIALIZER_CLASS_CONFIG, StringSerializer.class); props.put(ProducerConfig.VALUE_SERIALIZER_CLASS_CONFIG, StringSerializer.class); DefaultKafkaProducerFactory<String, String> factory = new DefaultKafkaProducerFactory<>(props); return new KafkaTemplate<>(factory); } }这样做的好处是你只带了发送消息的最小配置，不会像自动配置那样扫描一堆 consumer、listener 容器工厂。坏处是，如果你还需要消费消息，@KafkaListener依赖的那些容器工厂也得自己配，工作量明显变大，所以这种场景我更推崇 "保持自动配置 + 覆盖 Bean" 而不是整体排除。一把梭地排除所有自动配置，往往会遭遇到意想不到的 Bean 缺失问题。
4. 排除自动配置的常见坑与排查方法
4.1 排除了却没生效：类名与加载路径
很多人上来就写exclude = RedisAutoConfiguration.class，但启动日志里发现 Redis 相关的自动配置还是生效了。这种情况最常见的原因是类名引错了包。比如 Redis 的自动配置在早期版本是org.springframework.boot.autoconfigure.data.redis.RedisAutoConfiguration，但如果你用的是某些中间件封装包，它们可能有自己的自动配置类名，比如com.xxx.redis.XXXAutoConfiguration。你排除官方那个，人家自定义的还活着。
排除了却没生效的第二个原因是：自动配置类可能不是一个类，而是通过组合多个内部类实现的，比如DataSourceAutoConfiguration就包含多个内部配置类，你排除外层后，某些内部条件配置可能还是通过@Import从别的地方被引进来。还有一点容易忽视：exclude和excludeName只对@EnableAutoConfiguration加载的类生效，如果你项目里手动通过@Import或组件扫描把某些类引入了，排除是不会阻止它初始化的。
排查方法很简单，启动的时候加一个参数：
debug: true或者命令行--debug，Spring Boot 会在启动日志里输出一份条件评估报告，明确告诉你哪些自动配置类 condition 匹配通过，哪些没通过。你可以在报告里直接搜类名，看它到底是 "matched" 还是 "negative match"，如果它压根没出现在报告里，说明它根本不是通过自动配置机制加载的，排除自然徒劳。
4.2 排除后 Bean 缺失：补位配置怎么给
排除一个自动配置类之后，最常见的连锁反应就是其他模块需要注入的 Bean 找不到了。比如你排除了DataSourceAutoConfiguration，JdbcTemplateAutoConfiguration可能也会失效，因为它是建立在数据源存在的基础上的。此时你手动创建完DataSource，发现JdbcTemplate又没了，项目启动直接抛NoSuchBeanDefinitionException。
这时候要记住一个原则：排除不是目的，替代才是。每排除一个自动配置类，你都要想清楚它会连坐哪些 Bean，然后手动补齐。我建议用排查的思路列出依赖链：
- 排除
DataSourceAutoConfiguration后，手动补充DataSourceBean； - 如果项目用
JdbcTemplate，补充JdbcTemplateBean； - 如果项目用 MyBatis，补充
SqlSessionFactory和MapperScannerConfigurer； - 如果排除了
RedisAutoConfiguration，补充RedisTemplate； - 如果排除了
KafkaAutoConfiguration，补充KafkaTemplate或ConsumerFactory。
补位配置其实是个体力活，但对理解 Spring 容器非常有帮助。我甚至建议初学者刻意做一次"全排气实验"：把所有自动配置全部排除，只用@Configuration手写核心 Bean，你会瞬间理解自动配置有多贴心。
4.3 利用条件评估报告定位问题
条件评估报告是排查自动配置问题的最好工具，没有之一。启动应用时配置debug=true，日志里会输出CONDITIONS EVALUATION REPORT。它分正反两个列表：Positive matches列出生效的自动配置类和条件；Negative matches列出没生效的类和原因。例如：
Negative matches: RedisAutoConfiguration#redisTemplate Did not match: - @ConditionalOnMissingBean (types: org.springframework.data.redis.core.RedisTemplate; SearchStrategy: all) found beans of type 'org.springframework.data.redis.core.RedisTemplate' redisTemplate看到这种信息，你就知道 Redis 的模板没有被自动创建，是因为你已经手动定义了同类型 Bean。如果你想确认某个自动配置类是否被排除，直接在报告里搜它的类名，如果连 "Negative matches" 里都没有，那说明它在候选集合阶段就被过滤了。
在实际工作中，我会把这份报告重定向到日志文件里，方便全量搜索。比如：
java -jar app.jar --debug > startup.log 2>&1然后 grep 关键字：
grep -A 20 "DataSourceAutoConfiguration" startup.log这样定位既快又准，不用在 IDE 控制台里翻半天。
4.4 团队协作时的排除策略
自动配置的排除是一项全局性决策，放在哪一层直接影响团队协作的效率。我见过不少项目，今天有人往启动类加一个 exclude，明天有人往配置文件加一个，最后代码里东一处西一处，根本搞不清谁排除了谁。
我的建议是，把所有的"关键排除"集中管理。如果项目小、固定排除项少，统一放在启动类上是最好的，因为入口只有一个，新成员一眼能看到。如果项目模块多、环境差异大，那spring.autoconfigure.exclude配合 profile 专用配置文件更合适。但不管哪种，都要在代码注释里写清楚排除原因，不要只写一个类名，三个月后没人记得为什么排除。我的习惯是：
@SpringBootApplication(exclude = { // 不使用 Spring Boot 默认数据源，统一走 custom-datasource-starter DataSourceAutoConfiguration.class, // 使用自定义 RedisConfig 处理序列化，排除默认模板 RedisAutoConfiguration.class })这种注释成本极低，但能省下团队里大量 "这个 exclude 是哪位加的" 的疑问。
另外，如果团队引入了代码扫描工具，可以考虑让静态检查规则强制要求 exclude 旁边必须带注释，或者禁止在多个地方散落 exclude。这些细节看似繁琐，但真到项目出问题时，它们就是救命稻草。
5. 我在实际项目中总结的一点心得
自动配置排除这个功能，听起来是一行配置的事，但用好了是精细控制，用不好就是给自己挖坑。我自己在经过几次教训之后，总结出三条原则：第一，能用属性配置解决的问题，不要用排除；能用自定义 Bean 覆盖的，不要用排除；只有自动配置本身有 bug 或不符合项目硬性要求时，才动排除。第二，排除必须成对出现：排除了什么，就手动补什么，形成一个完整的手写配置块，不要留下半吊子。第三，每次排除都必须留注释，写清楚原因和日期，因为你没法保证三个月后的自己还记得当时的处境。
最后再分享一个小技巧：排除一个自动配置类之前，可以先在条件评估报告里查一下它匹配到的具体条件。很多时候你以为自己排除了罪魁祸首，实际上真正捣乱的是它内部@Import进来的辅助配置类。看清条件的全貌再动手，一锤定音的概率会高很多。希望这篇内容能帮你把 Spring Boot 的自动配置真正驯服，而不是被它默默牵着走。
