Spring Boot 数据源自动配置启动报错排查

"Failed to configure a DataSource: 'url' attribute is not specified and no embedded datasource could be configured." 这句话，只要写过一段时间的 Spring Boot，基本都会撞见，而且往往不止撞见一次。它出现的时机特别难受：应用启动到一半，日志刷了一大片，最后一段红色堆栈甩在脸上，进程直接退出。我第一次看到时盯着这句英文愣了几秒——本地 MySQL 明明装着，配置文件里也写了东西，凭什么说我没配 url？

这条报错属于 Spring Boot 里典型的"配置类问题"：报错信息本身没错，但它指的方向和大多数人以为的方向不一样。这篇文章就把这句话彻底拆开讲清楚：它到底是哪段自动配置在报错、为什么embedded datasource这个词才是解题钥匙、六种常见触发场景怎么对号入座、定位问题的三板斧、四种正解的适用边界，以及我在真实项目里踩过的那些坑。适合刚开始用 Spring Boot 做后端的朋友，也适合已经能跑项目但一遇到启动报错就只会删配置重来的同学。看完你至少能做到两件事：第一，看到这句话不再慌；第二，能根据当前工程形态，十分钟内选对修法。

1. 先把这条报错读明白：自动配置到底在找什么

1.1 报错信息的逐句拆解

这句话不是程序员手写的，它来自DataSourceProperties类的determineUrl()方法。方法内部逻辑很短：如果spring.datasource.url这个属性为空，就去尝试解析一个内嵌数据库的 url；两边都拿不到，就抛出DataSourceBeanCreationException，并把Failed to configure a DataSource作为提示语包装出去。

拆成三段看就清楚了：

• Failed to configure a DataSource—— 我（Spring Boot）正在尝试给你造一个DataSource类型的 Bean。
• 'url' attribute is not specified—— 但我读到的配置里没有可用的连接地址。
• no embedded datasource could be configured—— 我也没在 classpath 上找到能当内嵌数据库用的东西，所以连兜底方案都没有。

关键点在于：报错的主体是框架，不是你的数据库。它不是"连不上 MySQL"，而是"根本没走到连接这一步"。很多人第一反应是去检查 MySQL 有没有启动、端口通不通、账号密码对不对，方向从一开始就偏了。数据库服务就算关着，只要 url 写对了，报的会是Communications link failure或者超时，是另一套错误。分清楚这个区别，能省下大量瞎折腾的时间。

1.2 DataSourceAutoConfiguration 的条件装配逻辑

Spring Boot 的自动配置不是无脑全开，每个XxxAutoConfiguration类头上都挂着一串条件注解。和这条报错直接相关的是DataSourceAutoConfiguration，它的核心条件大概是这么几层：

1. 类路径上存在DataSource和EmbeddedDatabaseType这两个类（也就是引了spring-jdbc）。
2. 容器里目前没有用户自己定义的类型为DataSource的 Bean。
3. spring.datasource.type没有指向一个已经存在的其他数据源实现。

三个条件都满足，它才会生效，然后在内部再分两条支路：

• 如果DataSourceProperties能确定出一个 url，就用这个 url 去创建一个连接池数据源（默认 HikariCP）。
• 如果确定不出来，就尝试走EmbeddedDataSourceConfiguration，去 classpath 上找 H2、HSQLDB、Derby 这三种内嵌库。

所以整条链路是"先看你有没有配，再看有没有兜底"。你既没配真实连接，又没引内嵌库，两条路全断，异常就抛出来了。理解这一点之后，后面所有的解决方案其实都是在"补第一条路"或者"补第二条路"之间做选择。

1.3 为什么"embedded datasource"这个词才是解题钥匙

大部分人对这条报错的误读在于：只盯着'url' attribute is not specified，觉得是"我 url 写漏了"。但真正决定你要花多少时间修的，是后半句no embedded datasource could be configured。

它其实在提示你一件事：框架认为你现在需要一个能立刻用起来的数据源。它默认你的应用是要连数据库的，因为它看到了spring-jdbc这一类依赖。如果一个工程明明只是写个定时任务、做个 HTTP 转发、或者纯粹想跑个 Web 接口，压根不碰数据库，那问题就不该是"我该配哪个库的 url"，而是"为什么这个自动配置会被触发"。

我自己遇到过一个典型场景：项目里为了用JdbcTemplate做一批一次性数据清洗，加了个 JDBC starter，结果清洗逻辑写完了，那个依赖忘了删，导致整个 Web 应用启动时都要连数据库。这时候正确的解法不是补一个 url，而是把这个依赖摘掉，或者在启动类上把DataSourceAutoConfiguration排除掉。同一条报错，一个是"缺配置"，一个是"多依赖"，判断错了就要多绕好几圈。

2. 六种常见触发场景，对号入座比瞎改配置快得多

2.1 引了 JDBC 或 JPA 依赖却没配数据库

这是最常见的一种。pom.xml里加了spring-boot-starter-data-jpa或者spring-boot-starter-jdbc，但application.yml里只有端口、日志这些常规配置，一行数据库相关的都没有。自动配置发现 classpath 上有DataSource类，容器里又没有用户定义的DataSourceBean，于是启动装配，读配置发现是空的，抛错。

判断方法很简单，看依赖树里有没有这几个：

mvn dependency:tree | grep -E "spring-boot-starter-(jdbc|data-jpa|data-jdbc)|mysql-connector|postgresql"

如果有，那基本就是这个原因。修法也直白：要么把连接配置补上，要么把依赖去掉，要么排除自动配置。

2.2 配置写错层级或 YAML 缩进

yml是缩进敏感格式，一旦层级错位，属性就绑不到DataSourceProperties上，表现为"我明明写了 url，它却说没指定"。典型错误长这样：

spring: datasource: url: jdbc:mysql://localhost:3306/demo username: root

datasource和spring顶格对齐，看起来"平级"，实际上spring.datasource.url这个属性根本没生成，生成的是datasource.url。正确写法必须是：

spring: datasource: url: jdbc:mysql://localhost:3306/demo username: root password: 123456 driver-class-name: com.mysql.cj.jdbc.Driver

这类问题的隐蔽性在于：IDE 对yml的缩进提示并不总是显眼，而且有些编辑器会自动把 tab 转成空格，肉眼更难发现。我习惯的做法是配完先用application.yaml的自动补全敲一遍spring.datasource.，看 IDE 能不能把url、username这些提示出来。如果提示不出来，说明层级已经错了。

2.3 多数据源场景下手写配置覆盖了自动配置

只要项目里出现"多数据源"三个字，自动配置就必须让路。因为你要自己声明DataSourceBean，而DataSourceAutoConfiguration的条件之一就是"容器里没有用户自己定义的 DataSource Bean"。它一旦检测到你手写了，就会整体退让。

但这里有个坑：自动配置退让了，不代表那些 starter 里的其他自动配置也退让。比如 JPA 的HibernateJpaAutoConfiguration仍然会尝试去找一个EntityManagerFactory需要的DataSource，找不到同样会报类似的错。所以多数据源场景下，通常要配合@EnableAutoConfiguration(exclude = {DataSourceAutoConfiguration.class, DataSourceTransactionManagerAutoConfiguration.class, HibernateJpaAutoConfiguration.class})这样一组排除。

多数据源还有第二个常见坑：@ConfigurationProperties前缀写错。比如写成了spring.datasource.primary，但配置里是spring.datasource.master，绑定失败不会报错，只会静默留下一个空的DataSourceProperties，最后还是掉回原来的报错。

2.4 Profile 没激活导致配置压根没加载

把数据库配置写进了application-dev.yml，但启动时没有激活devprofile，主配置文件里又没有默认值，结果就是"配置文件里明明有 url，运行时却说没有"。这个原因在团队协作里特别常见，尤其是新同学拉了代码直接跑，忘了看 README 里关于 profile 的说明。

排查方式：启动时加上--spring.profiles.active=dev再看效果；或者在日志里搜The following profiles are active，确认实际生效的是哪些。如果用了多环境配置目录，还要确认spring.config.location或spring.config.additional-location有没有指向正确的位置。

2.5 依赖被动传递引入 starter

有时候你压根没打算用数据库，但依赖树里冒出来一个 starter。典型来源是：

• 某个公司内部工具包，为了做审计日志，在它的pom.xml里依赖了spring-boot-starter-jdbc。
• 某个中间件客户端，为了写自己的元数据表，把 JDBC starter 打进了传递依赖。
• 版本升级时，某个 starter 的内部依赖结构变了，原来不带的现在带上了。

这种问题最容易被误判成"配置丢了"，因为你看自己的pom.xml完全正常。判断方法是把dependency:tree的完整输出导出来，搜关键字，然后看是哪个直接依赖带进来的。找到之后，用<exclusions>排掉，或者接受它的存在、去做排除自动配置。

2.6 单元测试切片导致的上下文不完整

@DataJpaTest、@JdbcTest这类切片测试注解，默认会去装配一个内嵌数据库。如果你的项目里恰好没有 H2 之类的依赖，切片测试启动时同样会撞上这条报错。另一种情况是自己在测试类上写了@SpringBootTest，但测试用的配置文件application-test.yml里没有任何数据源配置。

处理方式有两种：一是给测试 scope 加上 H2，让它用内嵌库跑；二是把测试类改成不依赖数据库的层级，比如@WebMvcTest，再配合 mock。我个人倾向于第一种，因为切片测试本来就是给数据访问层准备的，给个 H2 天经地义，而且跑得快。

3. 定位问题的三板斧：从报错日志到自动配置报告

3.1 读完整堆栈，别只看第一行

这条报错的堆栈通常很长，第一行只是结果，关键信息在中间的Caused by段。往下翻能找到类似这样的内容：

Caused by: org.springframework.boot.autoconfigure.jdbc.DataSourceProperties$DataSourceBeanCreationException: Failed to determine a suitable driver class

或者：

Caused by: java.lang.IllegalStateException: Cannot load driver class: com.mysql.cj.jdbc.Driver

这两种完全是不同的病。前者是 url 没读到，后者是驱动类找不到——驱动找不到意味着 url 其实已经读到了，只是driver-class-name写错，或者 mysql 驱动依赖被provided作用域卡住了。只看第一行，你会以为是配置缺失；往下看三行，才知道真正该改哪里。

3.2 打开 debug 模式看条件评估报告

Spring Boot 有个非常好用的调试开关，加上之后启动日志里会打印所有自动配置的匹配情况：

java -jar demo.jar --debug

或者在配置文件里写：

debug: true

日志里会分成两大块：Positive matches和Negative matches。搜DataSourceAutoConfiguration，你会看到它匹配或未匹配的具体原因。比如：

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

这就是"被触发了"。如果看到的是did not match，那说明它压根没生效，报错可能来自别处。这个报告还能告诉你DataSourceProperties到底读到了哪些值，虽然不会直接打印 url，但能帮你确认条件判断的入口在哪。

3.3 用配置端点核对属性绑定结果

项目里如果有 Actuator，/actuator/configprops和/actuator/env这两个端点能救命。前者会按前缀列出所有@ConfigurationProperties的绑定结果，spring.datasource这一节底下到底绑上了什么，一目了然；后者会显示属性来源，能看出某个值是从哪个配置文件、哪个 profile、哪个环境变量来的。

有一次线上排查类似问题，最后发现是容器里注入了SPRING_DATASOURCE_URL环境变量，它的优先级高于配置文件，值却是个空串，把配置里的真实 url 覆盖掉了。这种问题不看env端点，靠读配置文件永远找不到。

注意：Actuator 端点会暴露配置信息，生产环境务必做好访问控制，不要把/actuator/env直接暴露在公网。

3.4 依赖树排查，确认是不是"多"出来的

前面提过被动依赖的问题，这里给一个实用的命令组合。先把完整依赖树导出，再按关键字过滤：

mvn dependency:tree -DoutputFile=tree.txt grep -n -B 20 "spring-boot-starter-jdbc" tree.txt

-B 20是往前翻 20 行，这样能看到到底是哪个父节点把 starter 带进来的。Gradle 用户对应的是：

gradle dependencies > tree.txt grep -n -B 20 "spring-boot-starter-jdbc" tree.txt

找到"元凶"之后，处理策略分两种：如果这个依赖确实是多余的，直接<exclusions>排掉；如果它是某个功能组件的必需依赖，那就接受它，转而用排除自动配置的方式处理。判断标准是：这个组件在运行期是否真的会去用数据源。如果它只是引了依赖但实际用不到，排掉最干净。

4. 四种正解和它们的适用边界

4.1 方案一：补上真实的数据库连接配置

适用范围最广，只要你的应用确实要连数据库，这就是唯一正解。以 MySQL 为例，一个能跑的最小配置是：

spring: datasource: url: jdbc:mysql://127.0.0.1:3306/demo?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai&useSSL=false username: app_user password: ${DB_PASSWORD:default_pwd} driver-class-name: com.mysql.cj.jdbc.Driver hikari: minimum-idle: 5 maximum-pool-size: 20 connection-timeout: 30000 idle-timeout: 600000 max-lifetime: 1800000

几个参数的解释：

• serverTimezone必须给，否则 MySQL 8 驱动在某些时区设置下会直接连接失败。
• useSSL=false在本地和内网环境建议显式写上，避免驱动默认尝试 SSL 造成的额外握手失败。
• password用了占位符加默认值的形式，这样本地开发不配环境变量也能跑，线上则通过环境变量注入真实密码。

如果你只是想验证配置是否正确，把spring.datasource.url写完之后启动一次，看到日志里出现 HikariPool 启动的字样，就说明连接池已经建起来了。

4.2 方案二：排除 DataSourceAutoConfiguration

当应用确实不需要数据库时，这是最干净的做法。在启动类上写：

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

也可以用配置的方式，不用改代码：

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

两种写法有区别。注解方式写在代码里，改起来要重新编译，但意图明确，别人一看就知道这个应用不连库；配置方式灵活，可以按 profile 分别控制，适合"本地不连、线上连"或者反过来的场景。我个人的偏好是：如果整个应用生命周期都不连库，就用注解；如果只是某个环境不连，就用配置。

要额外注意，如果项目里用了 MyBatis、JPA 这些组件，光排除DataSourceAutoConfiguration通常不够，还得把对应的自动配置一起排除，否则它们会继续尝试注入数据源，报错换了个名字而已。

4.3 方案三：引入内嵌数据库，本地和测试环境零配置

H2 是这条路的主力。加依赖：

<dependency> <groupId>com.h2database</groupId> <artifactId>h2</artifactId> <scope>runtime</scope> </dependency>

加完之后什么都不用配，Spring Boot 会自动创建一个内存库，url 形如jdbc:h2:mem:testdb。这时候再启动，报错就消失了。这个方案的适用场景非常明确：本地快速验证、单元测试、演示环境。不要用在生产，内存库重启就清空。

如果想让 H2 更接近真实数据库的行为，可以开启 MySQL 兼容模式：

spring: datasource: url: jdbc:h2:mem:testdb;MODE=MySQL;DB_CLOSE_DELAY=-1 driver-class-name: org.h2.Driver

DB_CLOSE_DELAY=-1的作用是让内存库在最后一个连接关闭后仍然保留，避免连接池回收连接导致数据被清掉。这个参数我在写集成测试时踩过坑：不加它，测试方法之间数据会莫名其妙消失。

提示：内嵌库适合开发和测试，但 SQL 方言和真实数据库存在差异，涉及复杂查询或特定函数的场景，还是建议在测试环境接真实库跑一遍。

4.4 方案四：多数据源的手动装配

多数据源的本质是"放弃自动配置，自己动手"。核心是给每个数据源单独定义一个DataSourceProperties前缀，然后手动构建DataSource。骨架大概是这样：

@Configuration public class PrimaryDataSourceConfig { @Bean @Primary @ConfigurationProperties("spring.datasource.primary") public DataSourceProperties primaryProperties() { return new DataSourceProperties(); } @Bean @Primary public DataSource primaryDataSource() { return primaryProperties() .initializeDataSourceBuilder() .type(HikariDataSource.class) .build(); } }

配套的配置：

spring: datasource: primary: url: jdbc:mysql://127.0.0.1:3306/db_primary username: root password: 123456 driver-class-name: com.mysql.cj.jdbc.Driver secondary: url: jdbc:mysql://127.0.0.1:3306/db_secondary username: root password: 123456 driver-class-name: com.mysql.cj.jdbc.Driver

这里最容易翻车的地方是@Primary。多数据源场景下，容器里会有多个DataSource类型的 Bean，事务管理器、MyBatis 的 SqlSessionFactory 在自动装配时无法判断用哪个，会直接报冲突。给主库加上@Primary是标准做法。同时记得把前面说的那几个自动配置排除掉，否则自动配置和你的手动配置会打架。

5. 参数与配置细节：那些容易翻车的写法

5.1 url 和 jdbc-url 的区别

这个坑几乎每个用 HikariCP 或多数据源的人都踩过。HikariCP 本身的属性名是jdbcUrl，而 Spring Boot 默认绑定的属性名是url。在单数据源、走自动配置的场景下，url会被自动转换成jdbcUrl传给 Hikari，所以没问题。

但一旦你手动创建HikariDataSource，或者用@ConfigurationProperties直接绑到 Hikari 上，就必须用jdbc-url：

spring: datasource: primary: jdbc-url: jdbc:mysql://127.0.0.1:3306/db_primary username: root

用错的表现是：启动不报错，连接池也建起来了，但一执行 SQL 就报jdbcUrl is required with driverClassName。因为 url 这个属性根本没人读，被忽略了。判断依据是看你构建数据源的方式：走DataSourceProperties.initializeDataSourceBuilder()用url，直接new HikariDataSource()加上属性绑定用jdbc-url。

5.2 密码特殊字符与占位符

数据库密码里带@、#、$这类字符是常态，在yml和占位符里都要小心。

• yml里如果值以特殊字符开头，建议用单引号包起来，比如password: '#123abc'。
• 用${DB_PASSWORD}占位符时，如果环境变量没定义且没给默认值，${DB_PASSWORD}会被原样当成字符串，导致认证失败，而不是报"变量未定义"。
• 想给默认值就用${DB_PASSWORD:default123}，冒号后面是兜底值。

我在一个项目里见过更隐蔽的：密码里有个$，写成了${abc123}，结果被 Spring 当成属性占位符去解析，找不到对应属性直接抛异常。这种错误排查起来很费时间，因为报错信息和数据库认证毫无关系。

5.3 连接池参数给一个能跑的基线

参数不要照抄网上的极端值，先给一个能稳定运行的基线，再根据压测结果调。参考表如下：

max-lifetime这条特别实用。MySQL 默认wait_timeout是 8 小时，如果连接池里的连接活过了这个时间，数据库端已经把连接掐了，但池子里还认为它可用，取出来执行 SQL 就会报Communications link failure。把max-lifetime设成 30 分钟，让连接在数据库掐断之前主动轮换，能规避掉一大类偶发报错。

5.4 初始化脚本的位置与执行顺序

用内嵌库或者需要初始化表结构时，脚本位置和版本差异很容易出问题。Spring Boot 2.5 之前，data.sql和schema.sql放在src/main/resources下会自动执行；2.5 之后引入了spring.sql.init前缀：

spring: sql: init: mode: always schema-locations: classpath:db/schema.sql >