企业官网建设流程全解析

如果你在Spring Boot项目里遇到过“这也自动配置了、那也自动配置了，我明明没让它这么做”的困惑，那么今天这篇关于Spring Boot 排除自动配置的经验分享应该能帮到你。我第一次深入使用这个功能，是因为一个多商户商城项目反复报数据源错误。项目里明明自定义了一套基于AbstractRoutingDataSource的多数据源路由，启动时却总是被Spring Boot默认的DataSourceAutoConfiguration抢在前面，直接说“Failed to configure a DataSource: 'url' attribute is not specified”。折腾了两个小时，最后在application.properties里加了一行spring.autoconfigure.exclude=...，世界清净了。

这篇文章适合正在被自动配置“误伤”的人，也适合想彻底搞懂“排除自动配置”到底排的是什么、为什么排了还会报警的同行。我会从自动配置的工作原理讲起，对比三种排除方式，再结合MyBatis、多数据源、Security等经典场景，还原一条完整排查链路。等你看完，再去面对那些启动时报错、配置冲突、自定义Bean被覆盖的问题，应该会有种“原来如此”的感觉。

1. 为什么需要排除自动配置：先弄懂它在背后做了什么

1.1 自动配置不是玄学，是一堆条件判断

很多人第一次接触Spring Boot，都会被“自动配置”四个字吸引。依赖加进去，程序一启动，功能就有了。但自动配置并不是魔法，它本质上是一堆以*AutoConfiguration结尾的Java类，这些类通过@Bean方法向容器注册组件，再配合@ConditionalOnClass、@ConditionalOnMissingBean、@ConditionalOnProperty等条件注解，决定自己要不要生效。

举个例子，DataSourceAutoConfiguration的核心逻辑是：只要classpath里能找到javax.sql.DataSource这个类，就尝试帮你创建一个DataSource。它并不知道你的项目里已经自己写了数据源路由，它只知道“有这个类，我猜你需要一个数据源”。这种“看菜下饭”的机制在大多数时候是省心的，但一旦你的需求超出它的预期，它就会变成阻碍。

自动配置类的位置也值得记住。Spring Boot 2.6及以前，所有自动配置类都注册在META-INF/spring.factories文件里，key是org.springframework.boot.autoconfigure.EnableAutoConfiguration；从2.7开始，逐步迁移到META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports文件，一行一个全限定类名。了解这个变化，能帮你在排查时快速找到“到底有哪些自动配置类可能被加载”。

1.2 常见不得不手动排除的几类场景

我自己的经验里，最常需要排除自动配置的场景大概有下面几类：

• 数据源冲突：项目用了多数据源、读写分离或自定义路由数据源，Spring Boot默认的DataSourceAutoConfiguration会和你的Bean“抢位置”。典型例子就是商城项目整合MyBatis时，因为忘记排除默认数据源，启动直接报错。
• 安全框架的默认行为：引入spring-boot-starter-security后，如果没有排除SecurityAutoConfiguration，项目会默认启用一套登录页和basic认证。很多大学生就业推荐系统这类校内项目，想用自定义JWT过滤器，结果一启动就被自动配置的登录页挡住。
• 用不上的自动配置：项目里某个依赖是通过传递依赖带进来的，比如只为了用一个小工具，却把MongoDB或Redis的驱动带进了classpath，于是对应的自动配置也跟着生效，白白创建连接池、占用端口。
• 启动速度优化：自动配置类的@Bean方法虽然多数是懒加载，但仍有不少会在启动阶段执行。如果有一堆没用的自动配置，启动日志会变得很长，排查问题也要多花时间。

你可以发现，上面的场景有一个共同点：自动配置生效时，并没有考虑你项目里的实际情况。它只根据“类在不在classpath里”和“有没有同名Bean”做判断。所以当你的需求特殊时，就得主动告诉Spring Boot：“这个你不用管，我来。”

1.3 排除是“拒绝默认决策”，不是“删代码”

这里必须先澄清一个概念。排除自动配置，不会删除任何jar包里的类，它只是不让这个自动配置类参与@EnableAutoConfiguration处理。你仍然可以在项目里通过@Bean手写同样的组件，两者并不冲突。

排除动作的粒度是“类”，而不是“包”。比如你排除了DataSourceAutoConfiguration，不代表DataSourceTransactionManagerAutoConfiguration、MybatisAutoConfiguration也会被排除。这些类是否生效，还要看它们自己的条件注解。说实话，第一次用的人特别容易在这里产生误解，以为一个排除就万事大吉，结果只排掉一个，后续报错依然存在。

2. 三种主流排除方法：注解、配置文件和条件覆盖

2.1 注解方式：@SpringBootApplication(exclude = ...)

最直观的排除方式，就是在启动类上指定exclude参数：

@SpringBootApplication(exclude = { DataSourceAutoConfiguration.class, DataSourceTransactionManagerAutoConfiguration.class }) public class MallApplication { public static void main(String[] args) { SpringApplication.run(MallApplication.class, args); } }

如果你没有用@SpringBootApplication，而是直接组合了@Configuration和@EnableAutoConfiguration，那么就把exclude参数放在@EnableAutoConfiguration上：

@Configuration @EnableAutoConfiguration(exclude = DataSourceAutoConfiguration.class) public class AppConfig { }

这种方式的好处是显式、直观，IDE里还能做类跳转。但缺点也很明显——排除项写死在代码里，如果不同环境需要不同的排除项（比如开发环境排除邮件自动配置，生产环境需要启用），改代码就不太优雅。

2.2 配置文件方式：spring.autoconfigure.exclude

我更推荐用配置文件控制排除项。在application.properties里：

spring.autoconfigure.exclude=org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration,org.mybatis.spring.boot.autoconfigure.MybatisAutoConfiguration

在application.yml里可以写成数组形式：

spring: autoconfigure: exclude: - org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration - org.mybatis.spring.boot.autoconfigure.MybatisAutoConfiguration

这个方案最大的优势是支持环境差异化。你可以把上面的配置放在application-dev.yml里，生产环境不写；也可以配合Spring Profile，在不同环境加载不同的排除清单。类名必须是完全限定名，多个类用逗号或列表分隔。我自己在维护多环境项目时，基本都以这种方式为主。

2.3 条件覆盖方式：自己定义同类型的Bean

有时候根本不需要显式排除，Spring Boot的条件机制已经考虑过这个问题。很多自动配置类上都有@ConditionalOnMissingBean注解，意思是：如果容器里已经有同类Bean，我就不创建了。

比如RedisAutoConfiguration里，如果你自己定义了一个RedisTemplate<String, Object>，它就会退位让贤。所以一个优雅的做法是：先确认自动配置类的源码条件，再在项目里手动注册覆盖Bean。这样既保留自动配置的兜底能力，又能在需要时精准接管。

@Configuration public class CustomRedisConfig { @Bean @ConditionalOnMissingBean public RedisTemplate<String, Object> redisTemplate(RedisConnectionFactory factory) { RedisTemplate<String, Object> template = new RedisTemplate<>(); template.setConnectionFactory(factory); return template; } }

这种做法的前提是你对容器里的Bean定义有足够了解。要是自动配置类压根没有@ConditionalOnMissingBean，比如某些自动配置就是铁了心要创建，那你只能用前面两种显式排除方式。

2.4 三种方式的取舍

说实话，前两种方式底层是同一个机制：@EnableAutoConfiguration的exclude属性，只是数据来源不同。注解方式把exclude传给SpringApplication，配置文件则通过spring.autoconfigure.exclude属性也被引擎读取并合并。所以没必要纠结哪个更好，项目里混着用也没问题，但建议统一入口，减少维护成本。

3. 实战排错：多商户商城项目对接MyBatis，自动配置冲突的完整排查过程

3.1 问题现场

先还原一个真实到让我记忆深刻的场景。一个基于Spring Boot + MyBatis的多商户跨境商城源码，接了一个自定义的DynamicDataSource，继承自AbstractRoutingDataSource，想按商户ID动态切换主库和从库。开发环境启动时，控制台刷出一大片红色报错：

*************************** APPLICATION FAILED TO START *************************** Description: Failed to configure a DataSource: 'url' attribute is not specified and no embedded datasource could be configured. Reason: Failed to determine a suitable driver class

这个报错的核心含义是：Spring Boot发现classpath里有javax.sql.DataSource和某个数据库驱动，于是DataSourceAutoConfiguration尝试自动创建DataSource；自动配置创建的DataSource会去读取spring.datasource.url等属性，而我们这版项目根本没有配置这些属性，因为路由数据源完全是动态的，不需要一个默认连接。

3.2 第一步：用debug模式拿到自动配置报告

面对这种问题，千万别急着瞎猜。先打开自动配置报告，看看到底是谁在作祟。在application.properties里加一行：

debug=true

重新启动，控制台会打印一大段CONDITIONS EVALUATION REPORT，分为Positive matches（正向匹配）和Negative matches（负向匹配）。如果只想看自动配置相关，重点看Positive matches里的条目。比如你会看到：

DataSourceAutoConfiguration matched: - @ConditionalOnClass found required classes 'javax.sql.DataSource', 'org.springframework.jdbc.datasource.embedded.EmbeddedDatabaseType'; - @ConditionalOnMissingBean found no 'dataSource' bean.

这行信息非常关键：DataSourceAutoConfiguration之所以生效，是因为classpath里有DataSource类，而且容器里没有自定义的DataSourceBean。当我们项目里用DynamicDataSource创建了Bean，但可能Bean名不叫dataSource，或者还没注册，就会让自动配置以为自己“被需要”。

3.3 第二步：判断要排除哪些类

从报错堆栈和自动配置报告里，我们能清晰地定位到DataSourceAutoConfiguration是罪魁祸首。但接下来麻烦来了：只排除它就够了吗？

以MyBatis场景为例，与数据源相关的自动配置类通常还有这几个：

• org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration
• org.springframework.boot.autoconfigure.jdbc.DataSourceTransactionManagerAutoConfiguration
• org.springframework.boot.autoconfigure.jdbc.JdbcTemplateAutoConfiguration
• org.mybatis.spring.boot.autoconfigure.MybatisAutoConfiguration（MyBatis starter自带的）

它们的依赖关系是：MybatisAutoConfiguration期望容器里有一个DataSource类型的Bean；DataSourceTransactionManagerAutoConfiguration也需要DataSource。如果你排除了DataSourceAutoConfiguration，却没有在项目里注册自定义DataSource，那么后面这几个类会因为找不到DataSource而自动进入Negative matches，这没关系。但只要你在项目里注册了自定义DataSource（比如DynamicDataSource），它们就会正常生效。

所以在这个场景下，正确的排除范围其实只有DataSourceAutoConfiguration一个类就够了。但如果你连MyBatis都要自己配置（比如完全手写SqlSessionFactory），那还要排除MybatisAutoConfiguration。判断依据很简单：你希望Spring Boot帮你管理哪些Bean，就把管理那个Bean的自动配置排除掉。

3.4 第三步：落地排除并验证

我们在application.yml里加入：

spring: autoconfigure: exclude: - org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration

重新启动，数据源报错消失。因为我们的DynamicDataSource正常注册，MyBatis的MybatisAutoConfiguration检测到DataSource存在，继续完成了SqlSessionFactory的创建。

但有一个细节要注意：排除DataSourceAutoConfiguration后，spring.datasource.url、spring.datasource.username这些属性全部失效。如果你还有项目是依赖这些配置直接生成默认数据源的，千万不要随手排除，否则启动不会报错，但等到真正执行SQL时会报“No qualifying bean of type 'DataSource' available”。

3.5 踩坑记录：排除之后仍然报错，多半是这三个原因

第一条，类名写错。你以为你写的是org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration，结果打成了org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration，少了一个a，或者多了个s，排除自然不生效。这种错还特别隐蔽，因为Spring Boot不会告诉你“排除的类不存在”。

第二条，版本差异。MyBatis的自动配置类在不同版本里包名不同。早期版本是org.mybatis.spring.boot.autoconfigure.MybatisAutoConfiguration，新版starter的自动配置类可能迁移到别的包名，请以实际jar包为准。这提醒我们排查时要先找到jar包里的类路径。

第三条，排除了但没用。有些自动配置类并不是只通过@EnableAutoConfiguration引入，而是被别的配置类用@Import引进来，或通过Spring Boot的AutoConfigurationImportSelector之外的其他机制加载。这时候只写spring.autoconfigure.exclude是压制不住的，需要找到它的引用源头，从源头处理。

4. 深入理解排除自动配置的影响范围：别把有用的也排掉

4.1 排除一个类，可能连坐多个Bean

自动配置类之间不是孤立的。排除DataSourceAutoConfiguration，影响的绝不仅仅是DataSource本身。比如JdbcTemplateAutoConfiguration依赖DataSource，DataSourceTransactionManagerAutoConfiguration依赖DataSource，MybatisAutoConfiguration也依赖DataSource。如果你在排除后没有手动提供DataSource，那么这些原本会默认创建的JdbcTemplate、DataSourceTransactionManager、SqlSessionFactory全部都不会被创建。

这不是Bug，而是Spring Boot的设计：条件注解大多是@ConditionalOnSingleCandidate(DataSource.class)或@ConditionalOnBean(DataSource.class)。数据源都不存在，这些依赖它的自动配置就自动放弃。理解这个机制后，你就知道为什么有人排除了DataSourceAutoConfiguration，结果连MyBatis都一起失效了。

所以在排除前，建议画一张“依赖关系图”在脑子里。最省事的办法是查阅官方文档或直接看自动配置类的源码，搞清楚它创建了什么Bean，又依赖哪些Bean。不要凭“感觉”随意排除，尤其是那些处于链路中间位置的自动配置类。

4.2 能通过条件属性解决的，尽量不排除

有些自动配置提供了开关属性，用起来比排除类更精准。比如RabbitAutoConfiguration会在设置了spring.rabbitmq.host后才真正创建连接工厂，而很多场景下，你只是不希望它在一启动就去连接而已。这种情况下，与其排除整个自动配置，不如通过配置属性来控制行为。

我的建议是：先查这个自动配置类有没有可关闭的开关，再看它是否有@ConditionalOnMissingBean可被覆盖，最后才考虑显式排除。因为最终目的不是“消灭自动配置”，而是“让自动配置做出符合预期的行为”。

4.3 与自定义配置类的协作套路

在实际项目中，排除自动配置常常和自定义配置类搭配出现。一个合理的写法是：启动类保留@SpringBootApplication，排除掉不想用的自动配置，然后定义专门的@Configuration类负责生产替代Bean。

@Configuration public class CustomDataSourceConfig { @Bean public DataSource dataSource() { DynamicDataSource routingDataSource = new DynamicDataSource(); // 设置目标数据源、默认数据源 return routingDataSource; } }

这样排除的动作很清晰，替代的Bean也有专门的管理位置。更重要的是，这种写法对团队协作友好：别人看到启动类的exclude列表，再到CustomDataSourceConfig里找替代实现，一条线就串下来了。如果你把排除项丢在某个莫名其妙的配置文件里，替代Bean又散落在三个配置类中，那半年后你自己都会骂自己。

5. 结合热搜场景：商城源码、就业推荐系统、VSCode开发中的常见排除实践

5.1 多商户跨境商城：典型排除清单

很多开源的多商户跨境商城项目是基于Spring Boot + MyBatis搭建的，而且往往自带多数据源、读写分离等设计。这类项目最经典的操作就是排除DataSourceAutoConfiguration，原因前面已经说过——动态路由数据源不需要默认的固定DataSource。如果你在搭建环境时看到类似“Failed to configure a DataSource”的报错，优先检查这个排除项。

下面是一份常见的商城项目排除清单，注意这是示例，实际要以项目依赖为准：

spring: autoconfigure: exclude: - org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration - org.mybatis.spring.boot.autoconfigure.MybatisAutoConfiguration # 如果你要自己构建SqlSessionFactory - org.springframework.boot.autoconfigure.data.redis.RedisAutoConfiguration # 如果你用了自定义Redis客户端

需要强调的是，不要把这份清单当万能盾。每个项目的依赖不同，自动配置赛跑的情况也不同。排除前一定要看报错和自动配置报告，确认是哪一匹“马”多跑了。

5.2 大学生就业推荐系统：Security自动配置的排除实践

再看另一个热搜场景——基于Spring Boot的大学生就业推荐系统。这种课程设计或毕设项目，通常喜欢引入spring-boot-starter-security来做权限控制，但很多团队成员只想用JWT + 拦截器实现登录判断，不想让Spring Security给你生成一个登录页和basic认证弹窗。

如果项目里已经定义了Spring Security的SecurityFilterChain，那么SecurityAutoConfiguration和UserDetailsServiceAutoConfiguration会让默认行为干扰你。一个常见配置是：

spring: autoconfigure: exclude: - org.springframework.boot.autoconfigure.security.servlet.SecurityAutoConfiguration - org.springframework.boot.autoconfigure.security.servlet.UserDetailsServiceAutoConfiguration

不过这里要提醒：如果你不是彻底摆脱Spring Security，而是想自定义过滤链，那么排除SecurityAutoConfiguration会导致整个安全自动配置失效，你必须手动创建SecurityFilterChain和必要的过滤器，否则安全问题会很严重。排除的安全红线是：确保你理解排除后会缺失什么，并能补齐。

我见过不止一个同学为了省事把Security自动配置全排除，结果项目在没有任何安全校验的状态下裸奔，那比自动配置冲突可怕多了。

5.3 在VSCode里快速定位自动配置问题

坦白说，VSCode对Spring Boot的支持虽然没有IDEA那么完善，但用来排查自动配置完全够用。你只需要做三件事：

第一，在application.properties里临时打开debug=true，启动后就能在终端看到完整的CONDITIONS EVALUATION REPORT。这个报告会列出所有自动配置类的匹配原因，是定位“谁动了我的DataSource”的第一手资料。

第二，用VSCode的Java插件打开spring-boot-autoconfigurejar所在目录，直接查看自动配置类源码。快捷键能跳转到jar包内的class，虽然反编译体验一般，但看条件注解足够了。

第三，Spring Boot Dashboard可以提供启动、Debug视图。在Debug模式下，你还可以配合断点查看DeferredImportSelector的执行过程，不过普通项目用到这个级别的场景不多。

5.4 顺带澄清：修改端口和排除自动配置是两回事

热搜词里有一个“spring boot修改demo 端口号”，和排除自动配置其实没有直接关系。修改端口用的是：

server.port=8081

这个属性由ServletWebServerFactoryAutoConfiguration读取。如果你自定义了WebServerFactoryCustomizer，通常会去调整它，而不是排除自动配置。真正需要排除ServletWebServerFactoryAutoConfiguration的场景极其少见，一般是在嵌入式Web容器与其他容器方案共存时。

这里想说的是，排查问题时别被网上的零散经验带偏。同一个报错可能是不同原因导致的，先搞清楚机制，再决定是改配置还是排除自动配置，而不是一上来就搜“排除某某”。

6. 调试技巧与个人经验：几个一般文档不会写的问题

6.1 看懂条件评估报告，比记住排除类名更重要

在自动配置报告里，Positive matches和Negative matches是最需要关注的两个部分。Positive matches代表某个自动配置类生效了，后面会列出它匹配到的条件；Negative matches则代表没生效，也会列出失败原因。当你想排查“为什么它偏要自动配置”时，就看Positive matches里对应的那个类。比如：

ConditionEvaluationReportLoggingListener reports: Positive matches: ----------------- DataSourceAutoConfiguration matched: - @ConditionalOnClass found required classes 'javax.sql.DataSource'

这一行已经把答案说得很直白：classpath里存在javax.sql.DataSource，所以它认为该干活了。你再去想“它为什么不等我手动配置”，逻辑就很清晰了——条件一满足，它就抢跑。

6.2 排除项不是越多越好

有一段时间，我写项目总喜欢把用不到的自动配置全部排除掉，觉得这样启动更快、更干净。但后来发现，排除项多了以后，代码阅读和维护都是负担。新同事看到启动类上一长串排除列表，根本不知道哪些是必须的，哪些是历史遗留。更重要的是，很多自动配置即使生效，也不会创建真正消耗巨大的连接或资源，只有在运行时被使用才会初始化。所以启动速度的提升可能远没有你想象得那么明显。

正确的态度是：只在发生实际冲突时排除，并且把排除原因写成注释。比如：

spring: autoconfigure: exclude: # 多商户项目使用自定义动态数据源，必须排除默认数据源自动配置 - org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration

这个注释能救未来的你和你的队友。

6.3 一个我常用的快速验证技巧

当你怀疑某个自动配置是问题根源时，先不要急着改配置文件。最快的验证方式是在启动类上临时加一条exclude，启动看是否解决；如果暂时还不行，就再把配置文件里的排除项也加上。因为两类排除最终会合并，所以这种“临时排除”非常高效。验证通过后，再把排除项整理到正式环境配置里。

如果你连自动配置类叫什么名字都不确定，可以用IDE的全局类搜索，输入*AutoConfiguration，然后结合你引入的starter名称推测。比如引了mybatis-spring-boot-starter，搜MybatisAutoConfiguration准没错。

6.4 最后再分享一点个人体会

排除自动配置这个功能，用得好是“点刹”，用得不好就是“拆车”。我在早期踩过不少坑，最深的体会是：不要急着找“排除哪个类”的答案，而是先弄清楚“为什么这个类会生效”。自动配置机制是一套非常聪明的条件决策系统，它并不愚蠢，只是不知道你的业务意图。你需要在它误判的时候，明确地告诉它“这个Bean我来管”。当你把视角从“找灵丹妙药”切换到“读懂条件决策”，Spring Boot对你来说才算真正入门了。