docker-compose环境变量无法覆盖Spring Boot配置文件参数

Spring Boot 2.x/3.x 原生支持全大写下划线命名的环境变量通过宽松绑定规则覆盖properties/yml配置，出现不生效问题基本都是以下几个原因，按顺序排查即可： #

1. 先确认环境变量是否真的注入到容器 #

先进入运行中的api容器执行命令，校验变量是否存在：

docker exec -it <替换为实际api容器名称> printenv | grep SPRING_DATASOURCE

• 如果命令执行后没有输出你在docker-compose里配置的SPRING_DATASOURCE_URL等变量：检查docker-compose.yml的缩进，environment字段必须和build、ports字段保持同级缩进，YAML对缩进敏感度极高，多一个空格就会导致配置解析失效。你贴出来的配置缩进是正确的，但要确认本地实际文件没有缩进错误。
• 如果能看到对应环境变量，但应用没有读取：问题出在应用启动逻辑上。

2. 修复Dockerfile启动入口的写法（最高发问题） #

绝大多数环境变量不传递的问题，都是Dockerfile里的启动命令写法错误导致的：

错误写法（会导致Java进程拿不到容器环境变量） #

# 错误：shell格式直接启动，部分场景下进程无法继承容器环境变量
ENTRYPOINT java -jar /app/api.jar
# 更严重的错误：启动命令里硬编码了配置参数，优先级高于环境变量
ENTRYPOINT java -jar /app/api.jar --spring.datasource.url=jdbc:mysql://localhost:3306/portfolio_dev

正确写法 #

用exec数组形式定义启动入口，让Java进程作为1号进程直接继承容器的全部环境变量：

ENTRYPOINT ["java", "-jar", "/app/api.jar"]

如果你用了自定义shell脚本做启动预处理，脚本内启动Java的命令必须加exec前缀，否则环境变量不会传递给Java子进程：

#!/bin/sh
# 其他预处理逻辑写在这里
exec java -jar /app/api.jar # 必须加exec，否则进程会丢失环境变量

3. 排查高优先级配置覆盖问题 #

Spring Boot配置有明确的优先级顺序，要确认没有比环境变量优先级更高的配置存在：

• 检查容器内jar包外部是否存在配置文件：如果Dockerfile把application.properties/application.yml拷贝到了容器的/config目录、应用工作目录，这些位置的配置优先级高于jar包内部配置和环境变量，会直接覆盖。
• 检查是否激活了特定profile：如果配置了spring.profiles.active=dev，对应的application-dev.properties配置优先级高于默认配置，也会覆盖环境变量。
• 检查代码逻辑：是否用@PropertySource注解加载了自定义配置文件，且手动设置了更高的优先级，会破坏默认的配置绑定规则。
• 检查是否配置了SPRING_CONFIG_LOCATION变量指定了外部配置路径，导致默认配置加载顺序异常。

4. 修复特殊字符导致的YAML解析错误 #

你当前配置里的数据库密码带$、(、%特殊字符，注册密钥是连续&，这些都是YAML的语法特殊字符，如果你用列表形式（- 变量名=值）写environment配置，很容易出现值解析错误，导致注入的变量值和预期不符。建议把environment改成键值对映射形式，所有带特殊字符的值用双引号包裹：

environment:
  SPRING_DATASOURCE_URL: "jdbc:mysql://mysql:3306/portfolio?useSSL=false&serverTimezone=UTC"
  SPRING_DATASOURCE_USERNAME: manager
  SPRING_DATASOURCE_PASSWORD: "替换为你的实际数据库密码"
  SECRET_REGISTRATION_KEY: "替换为你的实际注册密钥"

验证方法 #

修复后执行命令重新构建启动，查看日志里打印的数据源地址即可确认是否生效：

docker-compose up -d --build
docker-compose logs api | grep "jdbc:mysql"

正常情况下日志里输出的数据库地址应该是docker-compose中配置的jdbc:mysql://mysql:3306/portfolio，而非application.properties里的localhost地址。 #

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