Spring Boot 应用通过 Maven 命令传参与环境变量管理实战指南

本文详解如何使用 mvn spring-boot:run 传递 JVM 参数、应用参数及加载 .env 文件中的环境变量，并厘清 jvmArguments 与 arguments 的本质区别，助你构建可复现、易调试的本地开发流程。

本文详解如何使用 `mvn spring-boot:run` 传递 JVM 参数、应用参数及加载 `.env` 文件中的环境变量，并厘清 `jvmArguments` 与 `arguments` 的本质区别，助你构建可复现、易调试的本地开发流程。

在 Spring Boot 项目中，通过 Maven 命令启动应用（如 mvn spring-boot:run）是脱离 IDE、实现跨环境一致运行的关键方式。但许多开发者常混淆两类关键参数：JVM 级配置与应用级配置，也缺乏对 .env 文件标准化加载的支持。下面将系统性地给出生产就绪的实践方案。

✅ 一、正确区分并使用 jvmArguments 与 arguments

• mvn spring-boot:run -Dspring-boot.run.jvmArguments=...
  该参数向 JVM 进程本身 传递参数，影响内存、GC、调试端口等底层行为。例如：

  mvn spring-boot:run -Dspring-boot.run.jvmArguments="-Xmx512m -XX:+UseG1GC -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005"

  ⚠️ 注意：-Dspring-boot.run.jvmArguments 中的值会原样拼接到 java 命令行，不经过 Spring 解析，因此不能用于设置 Spring 属性（如 --server.port）。

• mvn spring-boot:run -Dspring-boot.run.arguments=...
  该参数向 Spring Boot 应用主类（main 方法） 传递参数，等效于 java -jar app.jar --xxx=yyy，支持所有 Spring Boot 支持的运行时参数：

  mvn spring-boot:run -Dspring-boot.run.arguments="--server.port=8081 --spring.profiles.active=dev"

  ✅ 此处 --server.port 和 --spring.profiles.active 将被 Spring Boot 的 SpringApplication 正确解析为环境属性。

✅ 二、通过 Maven 命令注入环境变量（无需修改代码）

Maven 本身不直接读取 .env 文件，但可通过以下两种可靠方式实现“环境变量注入”：

方式 1：Shell 层面导出（推荐，跨平台兼容性强）

# Linux/macOS
export DB_NAME=demo DB_USERNAME=postgres DB_PASSWORD=pass JWT_SECRET=appSecretKey
mvn spring-boot:run

# Windows PowerShell
$env:DB_NAME="demo"; $env:DB_USERNAME="postgres"; $env:DB_PASSWORD="pass"; $env:JWT_SECRET="appSecretKey"
mvn spring-boot:run

Spring Boot 默认自动读取系统环境变量（优先级高于 application.properties），上述变量将自动映射为 db.name、db.username 等 Spring 属性（遵循 relaxed binding 规则）。

方式 2：Maven 命令行显式传入（适合 CI/脚本化）

# 使用 -D 参数注入系统属性（注意：这是 System.setProperty，非 OS 环境变量）
mvn spring-boot:run \
  -DDB_NAME=demo \
  -DDB_USERNAME=postgres \
  -DDB_PASSWORD=pass \
  -DJWT_SECRET=appSecretKey

⚠️ 注意：这种方式设置的是 JVM 系统属性（System.getProperty()），需在代码中显式读取，不会自动绑定到 @Value("${db.name}") —— 除非你额外配置 systemProperties 源：

// 在启动类中（不推荐常规使用）
public static void main(String[] args) {
    System.setProperty("spring.config.import", "optional:env:");
    SpringApplication.run(MyApp.class, args);
}

✅ 三、优雅加载 .env 文件（无需插件，Spring Boot 2.4+ 原生支持）

从 Spring Boot 2.4 开始，官方支持通过 spring.config.import 导入 .env 文件（需配合 dotenv 格式）。无需第三方依赖或 Maven 插件：

1. 确保你的 .env 文件位于项目根目录（或 src/main/resources），内容如下：

   DB_NAME=demo
   DB_USERNAME=postgres
   DB_PASSWORD=pass
   JWT_SECRET=appSecretKey

2. 在 application.yml 或 application.properties 中声明导入：

   # application.yml
   spring:
     config:
       import: optional:file:.env[.properties]

   ✅ optional: 表示文件不存在时不报错；file: 表示从文件系统读取（支持相对路径）；.properties 是 Spring 对 .env 的隐式识别格式（键值对无需 export 前缀）。

3. 启动命令保持简洁：

   mvn spring-boot:run

   Spring Boot 会自动加载 .env 并将其作为 PropertySource，@Value("${db.name}") 可直接使用。

? 进阶技巧：按 profile 加载不同 .env 文件

# application-dev.yml
spring:
  config:
    import: optional:file:.env-dev[.properties]
---
# application-prod.yml
spring:
  config:
    import: optional:file:.env-prod[.properties]

? 总结与最佳实践

最后提醒：.env 文件切勿提交至版本库，应在 .gitignore 中加入：

.env
.env-*

掌握以上方法，你就能完全替代 IDE 启动配置，用一条 Maven 命令完成开发、调试与环境切换，真正实现“文档即运行说明”。