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

文章目录

[Spring Boot 环境变量配置详解：从 IDEA 到 Docker 部署](#Spring Boot 环境变量配置详解：从 IDEA 到 Docker 部署)
- 一、问题背景
- - [1.1 环境](#1.1 环境)
- 二、问题分析
- - [2.1 现象描述](#2.1 现象描述)
  - [2.2 根本原因](#2.2 根本原因)
  - - [1. Spring Boot RelaxedBinding 机制](#1. Spring Boot RelaxedBinding 机制)
    - [2. Linux 环境变量大小写敏感](#2. Linux 环境变量大小写敏感)
    - [3. 为什么 ` ${profile}\` 可以工作？](#3. 为什么 `$ {profile}` 可以工作？)
    - [4. 为什么 ` ${datasource_addr}\` 可能失败？](#4. 为什么 `$ {datasource_addr}` 可能失败？)
- [三、IDEA Spring Boot 启动配置详解](#三、IDEA Spring Boot 启动配置详解)
- - [3.1 Active Profiles（激活配置文件）](#3.1 Active Profiles（激活配置文件）)
  - [3.2 Environment Variables（环境变量）](#3.2 Environment Variables（环境变量）)
  - [3.3 VM Options（虚拟机参数）](#3.3 VM Options（虚拟机参数）)
  - [3.4 Program Arguments（程序参数）](#3.4 Program Arguments（程序参数）)
  - [3.5 参数优先级顺序](#3.5 参数优先级顺序)
- [四、Docker 部署最佳实践](#四、Docker 部署最佳实践)
- - [4.1 环境变量命名规范](#4.1 环境变量命名规范)
  - [4.2 Docker 环境变量传递方式](#4.2 Docker 环境变量传递方式)
  - - [方式一：docker run -e 参数](#方式一：docker run -e 参数)
    - 方式二：docker-compose.yml
    - 方式三：env_file
    - [方式四：CMD 参数传递](#方式四：CMD 参数传递)
  - [4.3 配置文件最佳实践](#4.3 配置文件最佳实践)
- 五、问题排查清单
- 六、总结

一、问题背景

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

yaml 复制代码

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 现象描述

环境	配置方式	结果
IDEA	进程传参（Program Arguments）	✅ 正常读取
Docker Linux	系统环境变量（-e 参数）	❌ 读取失败

2.2 根本原因

1. Spring Boot RelaxedBinding 机制

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

复制代码

datasource_addr → datasource.addr → DATASOURCE_ADDR → datasource-addr

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

阶段	RelaxedBinding 状态	说明
启动初期	完全生效	`spring.profiles.active` 等核心属性
Bean 初始化阶段	部分生效	数据源等组件初始化时

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

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

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

yaml 复制代码

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

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

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

yaml 复制代码

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 用逗号分隔

等效参数：

bash 复制代码

--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

示例：

bash 复制代码

-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

示例：

bash 复制代码

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

特点：

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

3.5 参数优先级顺序

从高到低：

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

四、Docker 部署最佳实践

4.1 环境变量命名规范

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

bash 复制代码

# ✅ 推荐
DATASOURCE_ADDR=10.xxx.xxx.xxx:5236
SPRING_PROFILES_ACTIVE=xprd

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

4.2 Docker 环境变量传递方式

方式一：docker run -e 参数

bash 复制代码

docker run -d \
  --name myapp \
  -e DATASOURCE_ADDR=10.xxx.xxx.xxx:5236 \
  -e SPRING_PROFILES_ACTIVE=xprd \
  myimage:latest

方式二：docker-compose.yml

yaml 复制代码

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

方式三：env_file

bash 复制代码

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

yaml 复制代码

# docker-compose.yml
version: '3.8'
services:
  myapp:
    image: myimage:latest
    env_file:
      - .env

方式四：CMD 参数传递

dockerfile 复制代码

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

bash 复制代码

docker run myimage:latest --datasource_addr=10.xxx.xxx.xxx:5236

4.3 配置文件最佳实践

推荐配置：

yaml 复制代码

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

说明：

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

五、问题排查清单

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

检查环境变量是否正确设置
bash 复制代码
```
# 在容器内执行
env | grep DATASOURCE
```

检查环境变量大小写

bash 复制代码

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

检查 Spring Boot 启动日志

复制代码

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

验证配置文件占位符

yaml 复制代码

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

检查 Dockerfile ENTRYPOINT/CMD

dockerfile 复制代码

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

六、总结

场景	推荐做法
IDEA 开发	使用 Environment Variables 或 Program Arguments
Docker 部署	使用大写环境变量名 + 下划线分隔
配置文件	占位符使用大写形式，保留默认值
多环境配置	通过 SPRING_PROFILES_ACTIVE 切换

核心原则：

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

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