Spring Boot外部化配置报错：驱动不接受jdbcUrl ${JDBC_DATABASE_URL}

安全阿岳

2026-8-29

问题诱因

占位符${JDBC_DATABASE_URL}未被解析直接传入JDBC驱动，本质是Spring属性解析机制未在配置加载阶段生效，常见原因如下：

自定义数据源/Liquibase配置时，直接将占位符字符串作为字面量写入代码，没有通过Spring的属性注入机制获取解析后的值。Spring Boot自动配置的数据源默认支持占位符解析，手动注册相关Bean时很容易遗漏占位符处理逻辑。
运行环境中JDBC_DATABASE_URL变量未被正确加载到Spring上下文的Environment中：平台默认会在应用运行时注入该环境变量，但本地调试未手动配置变量、启动时环境变量未透传给JVM进程时，低版本Spring Boot默认不会抛出占位符不存在的异常，而是直接将占位符字符串原样返回给调用方。
配置文件加载顺序异常：如果数据源相关配置写在Spring Boot默认不识别的自定义配置文件中，且没有显式配置占位符解析器关联该配置源，也会出现占位符无法解析的问题。

从报错栈来看，异常出现在Liquibase初始化阶段，本质是Liquibase读取数据源配置时拿到了未替换的占位符字符串，和数据源本身配置异常是同一个根因。

解决方案

按照优先级依次排查处理：

无自定义数据源Bean的场景，直接使用标准配置写法
在application.properties/application.yml中按如下格式配置即可：
```
spring.datasource.url=${JDBC_DATABASE_URL}
spring.datasource.username=${JDBC_DATABASE_USERNAME}
spring.datasource.password=${JDBC_DATABASE_PASSWORD}
```
注意：配置时不要给属性值加多余的单/双引号，否则会导致引号被当成连接串的一部分传入驱动，同样会触发URL校验失败。配置完成后Spring会自动读取环境变量替换占位符，自动配置的数据源、Liquibase都能正常读取到解析后的值。

存在自定义数据源/Liquibase配置的场景，通过属性注入传值
不要在代码中直接硬编码"${JDBC_DATABASE_URL}"字符串，通过@Value注解或构造器参数注入的方式，获取Spring解析后的实际连接地址：

@Configuration
public class DataSourceConfig {
    @Bean
    public DataSource dataSource(
            @Value("${JDBC_DATABASE_URL}") String jdbcUrl,
            @Value("${JDBC_DATABASE_USERNAME}") String dbUsername,
            @Value("${JDBC_DATABASE_PASSWORD}") String dbPassword
    ) {
        HikariConfig config = new HikariConfig();
        config.setJdbcUrl(jdbcUrl);
        config.setUsername(dbUsername);
        config.setPassword(dbPassword);
        return new HikariDataSource(config);
    }
}

如果单独为Liquibase配置了数据源，也要遵循同样的注入规则，不要直接传入占位符字面量。

确认运行环境变量加载正常
本地调试时，先在启动终端执行对应命令确认环境变量存在：
- Linux/macOS执行：echo $JDBC_DATABASE_URL
- Windows CMD执行：echo %JDBC_DATABASE_URL%
  使用IDEA等IDE本地启动时，需要在运行配置的环境变量项中手动添加数据库连接相关的环境变量，保证Spring能正常读取到对应值。
显式配置占位符解析规则，提前暴露配置问题
低版本Spring Boot可以添加如下配置，关闭“未解析占位符直接返回字符串”的默认行为，配置后如果存在变量缺失、占位符无法解析的问题，应用启动时会直接抛出明确的占位符解析异常，避免等到JDBC驱动校验阶段才报错：
```
@Configuration
public class PlaceholderConfig {
    @Bean
    public static PropertySourcesPlaceholderConfigurer propertySourcesPlaceholderConfigurer() {
        PropertySourcesPlaceholderConfigurer configurer = new PropertySourcesPlaceholderConfigurer();
        configurer.setIgnoreUnresolvablePlaceholders(false);
        return configurer;
    }
}
```

内容的提问来源于stack exchange，提问作者Bailey M