写一篇关于“Spring Boot 排除自动配置”的博客文章。我平时在帮团队排查各种启动异常时，最常打的交道就是自动配置。表面上@EnableAutoConfiguration帮我们省去了一大堆 XML，但一旦项目里引入了多个 Starter，平平无奇的“自动”二字就容易引出各种幺蛾子——数据源连错、缓存策略漂移、消息队列被莫名加载。今天就把“排除自动配置”这件事从头到尾捋清楚：什么时候必须排除、有哪些排除方式、怎么定位该排除谁，以及我踩过的一些坑。
1 核心概念与适配场景
1.1 为什么需要排除自动配置
先快速过一下基本原理。Spring Boot 在启动时会扫描META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports（老版本是spring.factories）中声明的所有自动配置类，然后根据类路径上的依赖、条件注解和自定义配置，决定要不要实例化这一批 Bean。
这套机制绝大部分时候是聪明的，但“聪明”也意味着它会在你不需要的时刻自作主张：
- 项目里只需要一个 REST 服务，没有配置任何数据源，但因为引入了
mybatis-spring-boot-starter，启动时就会去尝试自动配置数据源，找不到连接信息就直接报错。这种场景非常高频。 - 引入了多个同类型 Starter（例如同时有
RedisAutoConfiguration和 Redisson 的自动配置类），两者可能会争抢同一批 Bean 定义，导致缓存序列化策略不是你预期的那套。 - 某些基础组件（比如安全框架、消息队列、调度器）被中间的公共依赖间接带进类路径，你自己根本没有使用需求，但它依然会被激活。
自动配置本身不坏，坏的是“不需要的自动配置被激活”。排除自动配置，本质上就是在启动阶段主动关闭某一组自动装配逻辑，让框架只保留你需要的部分。
1.2 什么样的项目会用到排除
按我的经验来看，以下三类项目最常需要主动排除：
一类是单体服务内嵌了多种数据访问组件。比如你以 Spring Data JPA 为主，但公共模块里引入了 MyBatis，两个自动配置类都活跃时，SqlSessionFactory和EntityManagerFactory同时被创建，难以预料到底谁在管理事务。
另一类是中间件 HA 部署的场景。很多团队会引入多套缓存或消息客户端，但只使用其中一套；另一套仅仅为了在其他节点上备用。如果不排除非活跃客户端自动配置，启动时就会因为连不上备用节点而不断重试。
还有一类是自定义 Starter 与官方 Starter 混合的场景。自定义 Spring Boot Starter 如果命名不规范（比如包名和官方一致），极其容易把自动配置类重复装配，导致 Bean 冲突。
排除了不需要的自动配置后，最直接的好处是启动变快、日志变干净、上下文结构清晰，排查问题时不至于有额外干扰。
2 三种排除方式及其原理
排除自动配置的方式一共有三种，分别对应代码、配置文件和类名引用。它们的原理是同一套：Spring Boot 在创建AutoConfigurationImportSelector时，会优先读取你指定的排除集合。
2.1 使用 exclude 属性（面向类对象）
最粗暴也最清晰的方式是在启动类上直接指定：
@SpringBootApplication(exclude = { DataSourceAutoConfiguration.class, HibernateJpaAutoConfiguration.class }) public class Application { public static void main(String[] args) { SpringApplication.run(Application.class, args); } }这里的exclude是@EnableAutoConfiguration注解的属性，传入的是Class<?>数组。Spring Boot 会把被排除的类从后续所有加载逻辑中剔除，连条件评估机会都没有。
这种方式适合明确知道要排除哪一个类的场景，且这种排除是“全局性”的——整个应用上下文生效。如果你做的是库型项目，不建议硬编码排除，因为会直接断掉使用方扩展的可能。
有一点要注意：exclude传入的类必须能被类加载器加载。如果你在写公共模块，不希望硬依赖某个类，那就不能直接写XxxAutoConfiguration.class，因为你根本无法在编译期引用那个类。
2.2 使用 excludeName 属性（面向类名字符串）
exclude的问题是必须直接引用类，这在跨模块、跨 Spring Boot 版本时很不方便。比如你基于 Spring Boot 2.5 开发一个基础包，想排除新版才有的自动配置类，源码就无法编译。
excludeName就是为这种情况准备的：
@SpringBootApplication(excludeName = { "org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration", "com.example.common.autoconfigure.CustomLogAutoConfiguration" }) public class Application { public static void main(String[] args) { SpringApplication.run(Application.class, args); } }它和exclude除了类型不同（字符串数组 vs 类型数组），处理逻辑几乎一模一样，唯一的差别是框架会先尝试把字符串转换成类，如果转换失败则忽略并输出警告日志。
我建议自己写的通用组件库提供“排除开关”时，统一用excludeName+ 配置项组合，让使用方可以在application.yml里灵活调整，而不是必须改启动类。这需要配合第三种方式使用，见下节。
2.3 通过配置文件全局排除
第三种方式是在application.yml或application.properties中使用spring.autoconfigure.exclude：
spring: autoconfigure: exclude: - org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration - org.springframework.boot.autoconfigure.orm.jpa.HibernateJpaAutoConfiguration这种方式的优先级最高——它会覆盖启动类上的exclude和excludeName配置。我理解 Spring Boot 团队的设计意图是：配置文件才是运维和部署阶段真正可控的入口，代码层面的排除是开发期的默认值，运维可以随时用配置覆盖。
而且配置方式天然支持多环境差异化：你在application-dev.yml里不排除，在application-prod.yml里排除，同一套代码不用改。
要提醒一句：如果错误地在配置里排除了一些启动必不可少的自动配置类（比如ApplicationContextAutoConfiguration这种核心技术类），启动时会出现匪夷所思的错误堆栈。因为排除动作本身发生在 bean 加载之前，报错往往很晚，容易让人误判方向。
2.4 三种方式的选型建议
以上三种方式可以结合起来用，并不互斥。我通常的建议是：
- 自己写死的项目，直接
exclude，静态、清晰、IDE 里还能跳转。 - 需要做成公共组件的，用
excludeName，因为使用方不一定编译期依赖你的自动配置类。 - 面向部署和运维调优，强制用
spring.autoconfigure.exclude，避免动代码就上线。
如果把自动配置类比成“店铺的自动上架系统”，exclude就相当于你在后台手动下架某一商品，excludeName相当于给管理员一个商品 ID 列表让他们远程下架，配置文件方式则是给到店铺前台一张“禁止上架清单”，运营可以直接维护。
3 实战案例：排除数据源自动配置
数据源排除是最高频的应用，因为DataSourceAutoConfiguration在所有涉及 JDBC 的项目里都会被触发。下面用一个真实场景完整演示。
3.1 场景描述
假设项目引入了以下依赖：
<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>org.mybatis.spring.boot</groupId> <artifactId>mybatis-spring-boot-starter</artifactId> <version>2.3.1</version> </dependency>但项目做的是 HTTP 接口转发服务，不访问数据库。启动时经常会看到类似这样的报错：
Failed to configure a DataSource: 'url' attribute is not specified and no embedded datasource could be configured.原因很简单：MyBatis Starter 引入了spring-boot-starter-jdbc，JDBC 依赖在 classpath 里，所以DataSourceAutoConfiguration被激活。它想创建一个DataSource，但你没给 URL、账号密码，当然启动失败。
注意一个细节：Spring Boot 2.x 时代，如果 classpath 里刚好有 H2 之类的内嵌数据库依赖，它不会失败，而是悄悄用 H2 原始配置创建一个空数据源。这个行为更容易埋雷——服务能启动，但所有依赖数据源的 Bean 动态持有数据库连接池，数据库地址完全不是你预期的。
3.2 排除方案
在启动类排除 DataSource 自动配置：
@SpringBootApplication(exclude = { DataSourceAutoConfiguration.class }) public class PureWebApplication { public static void main(String[] args) { SpringApplication.run(PureWebApplication.class, args); } }如果项目里还引用了 JPA、JdbcTemplate 等依赖，连HibernateJpaAutoConfiguration和JdbcTemplateAutoConfiguration也一起排掉：
@SpringBootApplication(exclude = { DataSourceAutoConfiguration.class, HibernateJpaAutoConfiguration.class, JdbcTemplateAutoConfiguration.class }) public class PureWebApplication { public static void main(String[] args) { SpringApplication.run(PureWebApplication.class, args); } }大部分情况下，MyBatis Starter 场景只排DataSourceAutoConfiguration就够了，因为 MyBatis 自身的MybatisAutoConfiguration只在检测到数据源 Bean 时才生效。而 JPA 和 JdbcTemplate 那边是独立自动配置，建议按需排除。
3.3 排除后的验证
排除之后，启动日志里的自动配置报告会特意列出 Negative matches 或 Excluded 区段：
============================ CONDITIONS EVALUATION REPORT ============================ Positive matches: ... Negative matches: ... Exclusions: org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration看到Exclusions区出现这一类，就说明排除生效了。另外可以顺手用/actuator/conditions端点去实时查看当前生效的自动配置。如果你没开 actuator，也可以在启动参数加--debug，日志会全量打印自动配置评估报告。
核心经验：无论用哪种方式排除，都要确认最终类没有被其他自动化装配路径二次引入。特别留心DataSourceAutoConfiguration有一些变体（比如DataSourceTransactionManagerAutoConfiguration），你只排一个通常不够，要根据启动日志逐个排干净。
4 排除自动配置的定位方法论
说完了怎么排，更重要的其实是：怎么知道“到底该排除哪一个”。
4.1 启动失败起步排查
如果你的应用启动就报错，不要急着加排除。先看错误栈中Caused by附近是否出现了XXXAutoConfiguration字样。这个类名往往是第一嫌疑人。
例如错误栈里出现：
Caused by: org.springframework.beans.factory.NoSuchBeanDefinitionException: No qualifying bean of type 'org.springframework.data.redis.connection.RedisConnectionFactory'那就要反查是哪一个自动配置尝试创建了这个 Bean，可能是RedisAutoConfiguration，也可能是你自己引入的一个 Redis 工具包。
随后打开启动日志的 CONDITIONS EVALUATION REPORT，看 Positive matches 里有没有你没想到的自动配置类，这个列表会给你最大的排查信息量。凡是“我不知道它是谁”的类，都有可能是需要排除的对象。
4.2 使用 Java 配置覆盖而不是排除
有些场景，排除并不是最优雅的方案。比如你想用自己的 Redis 序列化策略，Spring Boot 默认的RedisAutoConfiguration提供了RedisTemplate，但它的序列化方式不符合你的要求。
这个时候，与其整个排除再手写全套 Bean，不如推荐在工程里声明覆盖 Bean。覆盖和排除的区别在于：
- 排除：整个自动配置类不执行，所有默认 Bean 都没有。
- 覆盖：
@Bean方法参数上用@ConditionalOnMissingBean感知，如果手动定义 Bean，自动配置自动退让。
只要你的自定义 Bean 定义时机早于自动配置的@ConditionalOnMissingBean检查，就会被识别为已存在，从而自动跳过默认创建。这种方式保全性更高，因为它保留了一部分框架逻辑（比如配置属性绑定）。
4.3 通过启动报告快速筛选
推荐一个快速筛选套路：
- 先用
--debug启动项目，拿到 CONDITIONS EVALUATION REPORT。 - 过滤出 Positive matches 列表。
- 从列表中挑出你不清楚作用、没有主动使用的自动配置。
- 到官方的自动配置源码中，查看核心
@ConditionalOnClass/@ConditionalOnProperty条件，判断它是因哪个依赖而入。 - 逐个排除，每排一个重启一次，观察是否影响业务功能。
注意：不要在没看报告的情况下凭空排除，很容易误伤核心配置。
4.4 条件化排除（自定义 Starter 的进阶玩法）
如果你在做自己的 Starter，想让使用方灵活控制排除粒度，我建议不要硬编码 excludeName，而是提供“自动配置条件开关”：
@ConditionalOnProperty(name = "myapp.logging.enabled", havingValue = "true", matchIfMissing = true) public class MyLoggingAutoConfiguration { ... }这样使用方只需要写：
myapp: logging: enabled: false就能达到“排除”效果，但操作路径是控制条件，而不是排除机制本身。这种方式的优势在于：使用方不需要知道被排除的具体类名，只需要知道你暴露的开关。
如果你的目标是做严格的排除型工具，则可以用@AutoConfigureBefore/@AutoConfigureAfter调整自动配置顺序，用来达到“让我的 Bean 后于你、并成功覆盖你”的效果，这也是替代 exclude 的一种思路。
5 常见问题与实战避坑
接下来整理几个我实战中频繁遇到的坑。这些问题如果只靠看官方文档，一般都踩不到点上。
5.1 排除后 Bean 依然存在？
遇到最多的假象是：排除了RedisAutoConfiguration，启动日志里依然出现 Redis 相关的 Bean。这种情况大概率是你的项目里引入了另一个自动配置类，比如SpringSessionAutoConfiguration、SpringDataRedisAutoConfiguration的变体。只排除一个入口类，不代表整个领域的所有入口都被排除。
排查方式依然靠 CONDITIONS EVALUATION REPORT，把 Negative matches 里所有Redis相关的类找出来，逐个排除。如果你发现某个类虽然被排除了，但其子装配类（比如RedisReactiveAutoConfiguration）还在，那就继续补刀。
5.2 排除类名写错导致启动静默失败
使用spring.autoconfigure.exclude时，如果字符串类名拼错了，Spring Boot 会忽略它，并在控制台输出一条警告日志：
Error processing condition on ...这种日志很容易被忽略，而且最终效果是你以为排除了，实际上没有。我在做组件库时专门遇到过，代码里excludeName写错了官方类名的大小写，启动没报错，但问题依旧存在，排查了半小时。
建议：写完排除清单后，启动日志里搜Exclusions关键词，确认你要排除的每一个类都真实出现在这个区段里。如果某个类没出现，多半是你拼错了，或者类在整个类路径中压根不存在。
5.3 Spring Boot 3 对自动配置的新限制
Spring Boot 3.0 之后的版本中，自动配置的 JDK 代理机制和初始配置加载流程有变化。spring.factories机制被AutoConfiguration.imports取代，很多老教程里让你在spring.factories里写EnableAutoConfiguration排除配置已经不生效了。Spring Boot 3 里，只认imports文件，所以你在写自定义 Starter 或排查排除逻辑时，确认自己看的是 3.x 的源码结构。
另外，Spring Boot 3 基于 Spring Framework 6，exclude属性本身依然存在，官方建议还是优先在application.properties配置spring.autoconfigure.exclude，因为它对启动流程侵入性更小。
5.4 排除可能引发隐式依赖缺失
DataSourceAutoConfiguration往往不只是帮你创建一个数据源，它可能顺带帮你配置事务管理器。你排除了它，但项目里恰好还有一个地方直接注入了PlatformTransactionManager，那启动时会直接因找不到对应 Bean 而失败。
解决办法是：先排查排除后还有哪些 Bean 是缺失的，再决定要不要手动补一个空实现。实际项目里这种“排除连带效应”很常见，不要只盯着当前报错，要顺着 Bean 依赖链路补全。
5.5 条件注解和排除的互斥关系
很多人在自动配置类上同时使用@ConditionalOnClass和@ConditionalOnMissingBean。排除机制是在这些条件评估之前生效的——类被排除后，整个配置类不会被解析，注释里的条件根本没有执行机会。
所以如果你排查到某个 Bean 没有产生，而你既排除了相关类，又写了@ConditionalOnMissingBean判断，不要困惑。排除优先于条件。
5.6 老项目从注解配置迁移到配置文件的建议
由于spring.autoconfigure.exclude优先级高于启动类上的exclude，如果在配置里误配置了一个永远不会加载的类，它不会有任何影响；但如果配置里漏掉了之前代码里已经排除的类，那么启动后行为就变了。
我在迁移老项目时，习惯先把所有代码级排除原封不动搬到配置文件里，并将其作为独立 profile 管理，然后再逐项对比启动日志，确认每个排除项都真实生效。这是最稳的一条路径。
6 从“排除”到“掌控自动配置”的更高层次
最后分享一点心得体会。
单纯会写exclude属性其实只是技术操作的上游。当你真正接触过各种复杂项目后，会发现自动配置管理的核心价值在于“可观察性”和“可控性”，不是“暴力排除”。
我在自己维护的基础包里，会专门写一个 Endpoint，把项目当前所有生效的自动配置类按模块分组输出到/actuator/custom-autoconfigurations，供运维和开发随时查看。这样做有一个很大的好处：团队内新人在排查问题时，不再需要翻原始启动日志，直接用可视化界面就能看到上下文里到底装载了哪些东西。启动时间普遍也降了 20% 到 30%，主要源于没用的自动配置不会再去触发大量@ConditionalOnXxx的判断。
另一个经验：排除自动配置之前，先审视你的依赖设计。如果同一个功能有三四个自动配置实体在争抢同一个 Bean，最合理的方案往往是根因上解决——剔除重复依赖或统一配置项。排除只是治标，依赖治理才是治本。
当然，实际场景里总有历史包袱和第三方限制。在这种条件下，掌握了exclude、excludeName、spring.autoconfigure.exclude这三种手段，再配合自动配置报告定位问题，已经足以应付九成以上的异常场景。
真遇到 FreeMarker、Thymeleaf、Jackson、Redis、DataSource、JPA、Mongo 等一堆自动配置同时生效的情况，建议按“单个模块逐个派生测试”的方式去排查，不要一次批量排除十几个类，否则出了问题都不知道是谁的锅。
这篇文章是我多年写服务、修故障的经验总结，希望对正卡在自动配置坑里的朋友有点帮助。如果你按照上面的方式排除了但还是不行，多半不是排除的问题，而是依赖本身在作祟，老老实实把依赖树摊开来看，远比盲目加排除项可靠。
