Spring Boot 环境变量配置详解：从 IDEA 到 Docker 部署

Spring Boot 环境变量配置详解：从 IDEA 到 Docker 部署

一、问题背景

在 Spring Boot 项目开发中，我们经常使用配置文件中的占位符来引用环境变量，例如：

url:jdbc:mysql://${datasource_addr:10.xxx.xxx.xxx:5236}/mydb

然而，一个常见的问题是：同样的配置在 IDEA 中运行正常，但部署到 Docker 的 Linux 环境后却无法读取环境变量。

本文将深入分析这个问题的原因，并介绍 IDEA 中 Spring Boot 的启动配置参数，帮助开发者更好地理解和解决环境变量配置问题。

1.1 环境

• jdk 17
• springboot 3.4

二、问题分析

2.1 现象描述

2.2 根本原因

1. Spring Boot RelaxedBinding 机制

Spring Boot 提供了 RelaxedBinding（宽松绑定）机制，允许属性名以多种形式映射：

datasource_addr → datasource.addr → DATASOURCE_ADDR → datasource-addr

但这个机制在不同阶段有不同的表现：

2. Linux 环境变量大小写敏感

• Windows：环境变量不区分大小写，profile和PROFILE等价
• Linux：环境变量严格区分大小写，profile和PROFILE是不同的变量

3. 为什么${profile}可以工作？

spring:profiles.active:${profile:default}

• profile在 Spring Boot 启动的最早期被解析
• 此时 RelaxedBinding 机制完全生效
• Spring 会自动尝试PROFILE、profile等多种形式

4. 为什么${datasource_addr}可能失败？

url:jdbc:mysql://${datasource_addr:10.xxx.xxx.xxx:5236}/mydb

• datasource_addr在数据源初始化阶段被解析
• 此时 RelaxedBinding 可能不完全生效
• 下划线_在不同环境下的处理方式不同
• Linux 环境下需要使用大写形式DATASOURCE_ADDR

三、IDEA Spring Boot 启动配置详解

在 IDEA 中运行 Spring Boot 应用时，可以通过以下几种方式配置参数：

3.1 Active Profiles（激活配置文件）

用途：指定激活的 Spring Profile

配置方式：

• 在 Run/Debug Configurations 中设置Active profiles
• 多个 profile 用逗号分隔

等效参数：

--spring.profiles.active=dev,test

示例：

Active profiles: xprd

3.2 Environment Variables（环境变量）

用途：设置进程级别的环境变量

配置方式：

• 在 Run/Debug Configurations 中设置Environment variables
• 格式：KEY=VALUE，多个用分号分隔

示例：

DATASOURCE_ADDR=10.xxx.xxx.xxx:5236 PROFILE=xprd

特点：

• 在所有操作系统上行为一致
• Spring Boot 会自动读取这些环境变量
• RelaxedBinding 机制完全生效

3.3 VM Options（虚拟机参数）

用途：传递 JVM 参数或系统属性

配置方式：

• 在 Run/Debug Configurations 中设置VM options
• 系统属性格式：-Dproperty=value

示例：

-Dspring.profiles.active=xprd-Ddatasource_addr=10.xxx.xxx.xxx:5236-Xms512m-Xmx1024m

特点：

• 通过System.getProperty()获取
• 优先级高于环境变量
• 适合传递 JVM 配置参数

3.4 Program Arguments（程序参数）

用途：传递命令行参数

配置方式：

• 在 Run/Debug Configurations 中设置Program arguments
• 格式：--key=value或key=value

示例：

--spring.profiles.active=xprd--datasource_addr=10.xxx.xxx.xxx:5236

特点：

• Spring Boot 自动解析--key=value格式
• 优先级最高
• 适合覆盖配置文件中的属性

3.5 参数优先级顺序

从高到低：

1. Program Arguments（程序参数）
2. VM Options（系统属性）
3. Environment Variables（环境变量）
4. application-{profile}.yml（配置文件）
5. application.yml（默认配置）

四、Docker 部署最佳实践

4.1 环境变量命名规范

推荐做法：使用大写字母 + 下划线

# ✅ 推荐DATASOURCE_ADDR=10.xxx.xxx.xxx:5236SPRING_PROFILES_ACTIVE=xprd# ❌ 不推荐datasource_addr=10.xxx.xxx.xxx:5236spring.profiles.active=xprd

4.2 Docker 环境变量传递方式

方式一：docker run -e 参数

dockerrun-d\--namemyapp\-eDATASOURCE_ADDR=10.xxx.xxx.xxx:5236\-eSPRING_PROFILES_ACTIVE=xprd\myimage:latest

方式二：docker-compose.yml

version:'3.8'services:myapp:image:myimage:latestenvironment:-DATASOURCE_ADDR=10.xxx.xxx.xxx:5236-SPRING_PROFILES_ACTIVE=xprd

方式三：env_file

# .env 文件DATASOURCE_ADDR=10.xxx.xxx.xxx:5236SPRING_PROFILES_ACTIVE=xprd

# docker-compose.ymlversion:'3.8'services:myapp:image:myimage:latestenv_file:-.env

方式四：CMD 参数传递

# Dockerfile ENTRYPOINT ["java", "-jar", "app.jar"] CMD ["--spring.profiles.active=xprd"]

dockerrun myimage:latest--datasource_addr=10.xxx.xxx.xxx:5236

4.3 配置文件最佳实践

推荐配置：

spring:datasource:url:jdbc:mysql://${DATASOURCE_ADDR:10.xxx.xxx.xxx:5236}/mydbprofiles:active:${SPRING_PROFILES_ACTIVE:default}

说明：

• 占位符使用大写形式${DATASOURCE_ADDR}
• 保留默认值作为兜底
• 与 Linux 环境变量命名规范一致

五、问题排查清单

当遇到环境变量读取问题时，按以下步骤排查：

1. 检查环境变量是否正确设置

   # 在容器内执行env|grepDATASOURCE

2. 检查环境变量大小写

   # Linux 区分大小写echo$DATASOURCE_ADDR# 正确echo$datasource_addr# 可能为空

3. 检查 Spring Boot 启动日志

   # 查看实际加载的配置 DEBUG=true java -jar app.jar

4. 验证配置文件占位符

   # 确保占位符格式正确${VARIABLE_NAME:default_value}

5. 检查 Dockerfile ENTRYPOINT/CMD

   # 确保 ENTRYPOINT 使用 exec 形式 ENTRYPOINT ["java", "-jar", "app.jar"]

六、总结

核心原则：

1. 环境变量命名统一使用大写 + 下划线
2. 配置文件占位符与环境变量名保持一致
3. 始终提供默认值作为兜底
4. 充分理解 Spring Boot 属性绑定机制