1. 为什么java -jar 指定配置文件这件事值得单独写一篇先说实话Spring Boot 项目做多了之后很多人对配置文件的态度是能跑就行——开发环境application.properties一写mvn spring-boot:run一敲完事。直到有一天你需要在服务器上部署或者要给客户演示一套带测试数据的系统才发现同一个 jar 包要面对完全不同的数据库地址、Redis 密码、日志级别这时候怎么让 jar 包读到我想要的那份配置就成了绕不过去的坎。我见过不少同事在这个问题上翻车。有人把生产库的地址直接写进了application-prod.properties然后提交到 Git有人用--spring.profiles.activedev启动结果发现配置压根没生效因为配置文件的名字没对齐还有人为了切换环境同时维护三份打好的 jar 包磁盘空间和心智负担一起爆炸。这些问题的根源其实都是没搞明白 Spring Boot 外部化配置的加载顺序和java -jar启动参数的作用机制。这篇文章就围绕java -jar启动 Spring Boot 应用时指定配置文件这件事把几种主流实现方式讲透。内容包括--spring.profiles.active指定 profile、--spring.config.location指定外部配置路径、--spring.config.additional-location追加配置目录、环境变量SPRING_CONFIG_LOCATION的使用以及它们之间的优先级关系。适合正在做部署脚本、Docker 镜像封装、或者被多环境配置折磨的 Java 开发者尤其是那些刚把 Spring Boot 项目从本地跑到服务器、还没完全吃透配置加载机制的读者。先说一个最反直觉的结论Spring Boot 的配置加载顺序里命令行参数是最高优先级之一但这并不代表你随便写个参数它就能生效。配置文件名、参数格式、路径写法、profile 与 location 的组合方式任何一环出错应用都会安静地用默认配置启动——这恰恰是最危险的情况因为应用没报错但连的数据库可能根本不是你想连的那一个。2. 先厘清 Spring Boot 配置文件加载机制否则后面全是坑2.1 约定优于配置为什么叫application这个名字Spring Boot 的核心思想是约定优于配置。当你运行一个 jar 包时它会自动在 classpath 根路径下寻找名为application.properties或application.yml的文件也支持application.yaml。这个约定省去了手动指定配置文件的麻烦但也带来一个问题如果你不想用这个名字或者想把配置放在 jar 包外面就必须打破约定而打破约定的方式就是本文要讲的这些启动参数。很多人不理解为什么 Spring Boot 要设计成先找application.properties再找带 profile 的application-{profile}.properties这样的模式。实际上这是为了把基础配置和环境差异配置分开。基础配置放数据库连接池参数、通用开关环境差异配置放不同环境的数据库地址、日志级别。比如application.properties # 公共配置 application-dev.properties # 开发环境 application-test.properties # 测试环境 application-prod.properties # 生产环境当你通过--spring.profiles.activeprod启动时Spring Boot 会先加载application.properties再加载application-prod.properties后者覆盖前者的同名配置项。这就是 profile 机制的核心逻辑。2.2 配置文件加载顺序优先级表Spring Boot 官方文档给出了一套完整的配置加载顺序从高到低大致如下优先级配置来源典型示例1最高命令行参数--server.port80812Java System 属性-Dserver.port80813操作系统环境变量SERVER_PORT80814外部配置文件jar 包外./config/application.properties5内部配置文件jar 包内classpath:/application.properties6最低代码中的默认值Value(${server.port:8080})这套优先级决定了我们后面所有指定配置文件方式的生效范围。比如你通过命令行指定--spring.config.location本质上是在告诉 Spring Boot别找默认位置的配置文件了去我指定的地方找。这个参数的作用范围是替换默认搜索路径而不是追加。2.3 最容易搞混的两组概念profile 与 location要理解配置文件指定方式必须先分清--spring.profiles.active和--spring.config.location这两类参数的区别。前者是激活某个已经存在的 profile 配置后者是重新指定配置文件的位置。打个比方profile 机制就像你有一本手册手册里分章节写了开发环境配置生产环境配置激活某个 profile 就是翻开对应的那一章而 config.location 机制则是告诉你手册放在哪个书架上甚至告诉你这本书其实不叫 application.properties叫别的名字也行。这两者不是互斥的实际使用中经常组合。比如指定一个外部目录同时激活生产 profileSpring Boot 就会去外部目录下找application-prod.properties来加载。但如果你只指定了 location没有激活任何 profile那它就只加载你指定位置里的application.properties或application.yml。提示--spring.config.location有一个非常容易踩的坑——它会完全替代默认的加载位置。也就是说如果你指定了/etc/myapp/作为 locationjar 包内部的application.properties就不会再被加载了。如果你希望外部配置优先但 jar 包内的配置作为兜底应该用--spring.config.additional-location而不是--spring.config.location。这个区别我在下文会展开讲。3. 方式一--spring.profiles.active指定环境 profile3.1 最常规的指定方式这是最简单、也是大多数项目首选的方案。前提是你的项目里已经按环境拆分了多个配置文件比如config/ ├── application.properties ├── application-dev.properties ├── application-test.properties └── application-prod.properties然后在启动时加上java -jar myapp.jar --spring.profiles.activeprod这样 Spring Boot 会加载application.properties公共配置和application-prod.properties生产环境配置后者覆盖前者的同名属性。多个 profile 同时激活也是可以的用逗号分隔java -jar myapp.jar --spring.profiles.activeprod,redis-cluster这种用法的场景是把环境和技术组件的配置拆成不同的 profile 文件。比如application-prod.properties管环境相关的数据库地址application-redis-cluster.properties管 Redis 集群模式配置两个 profile 可以独立组合。不过说实话profile 拆得太细也会带来管理负担我的建议是环境维度dev/test/prod和特殊场景维度redis-cluster、mq-enable 这类开关型配置分开别把每个小配置项都做成一个 profile。3.2 为什么不生效的排查思路--spring.profiles.active最经典的翻车现场是配置文件名不对。Spring Boot 对 profile 文件名的匹配规则非常严格当你指定--spring.profiles.activepro时它只会去找application-pro.properties或application-pro.ymlapplication-prod.properties不会被加载即使两者名字相似。Spring Boot 不会做模糊匹配名字对不上就静默忽略。另一个常见问题--spring.profiles.active写在java -jar命令的哪个位置答案是参数顺序无关紧要可以放在-jar myapp.jar之前或之后。但如果你用的是java -jar myapp.jar --spring.profiles.activeprod这个参数会被 Spring Boot 识别为应用参数如果你写成java -jar myapp.jar -Dspring.profiles.activeprod那它就是 JVM 系统属性。注意-D必须放在-jar之前否则 JVM 不会把它当作系统属性处理。# 正确-D 参数在 -jar 之前 java -Dspring.profiles.activeprod -jar myapp.jar # 也可以应用参数在 -jar 之后同样生效 java -jar myapp.jar --spring.profiles.activeprod这里有个细节-Dspring.profiles.activeprod和--spring.profiles.activeprod最终都能激活 profile但生效路径不同。前者是 JVM 系统属性Spring Boot 的SpringApplication会读取系统属性作为配置源后者是命令行参数直接进SpringApplication的参数列表。因为命令行参数优先级高于系统属性如果你同时写了两种方式--spring.profiles.active会覆盖-Dspring.profiles.active。3.3 补充一个不太常用但有用的技巧启动时临时覆盖单个配置项除了激活 profilejava -jar启动时还可以直接覆盖任意单个配置项这其实和指定配置文件是同一套机制。比如你不想改配置文件只想临时把端口换掉java -jar myapp.jar --spring.profiles.activeprod --server.port8082这条命令里--server.port8082是最高优先级的命令行参数会覆盖application-prod.properties里的server.port。这个技巧在排查线上问题时特别好用——不用重新打包、不用改配置直接带参启动就能验证某个配置项对应用行为的影响。4. 方式二--spring.config.location指定外部配置文件4.1 完全接管配置加载路径--spring.config.location的作用是重新指定 Spring Boot 搜索配置文件的位置。它的值可以是文件路径也可以是目录路径。指定文件时Spring Boot 会精确加载该文件指定目录时会在该目录下按默认命名规则查找。最常见的用法是指定一个外部配置文件java -jar myapp.jar --spring.config.location/etc/myapp/application.properties或者指定一个目录java -jar myapp.jar --spring.config.location/etc/myapp/当指定目录时Spring Boot 会按以下顺序在那个目录下查找application.properties、application.yml、application-{profile}.properties如果激活了 profile。4.2 必须重视的替换语义这里必须再次强调--spring.config.location是替换默认的搜索路径。默认情况下Spring Boot 会从classpath:/、classpath:/config/、file:./、file:./config/这几个位置搜索配置文件。一旦你指定了 location这些默认位置全部失效只从你指定的位置加载。--spring.config.location可以同时指定多个位置用逗号分隔例如java -jar myapp.jar --spring.config.location/etc/myapp/config/,/opt/myapp/application.yml多个位置之间也存在优先级关系越靠后的位置优先级越高。也就是说/opt/myapp/application.yml里的配置会覆盖/etc/myapp/config/目录下同名配置项的取值。这个替换语义带来的后果是如果你指定的外部配置里缺少 jar 包内application.properties中的某些配置项应用启动后这些配置项就是null或默认值可能直接导致启动失败或运行异常。因此使用--spring.config.location时必须确保你自己提供的配置文件是完整的而不是只放几个差异项。注意--spring.config.location从 Spring Boot 2.4 开始支持可选位置语法用optional:前缀标记。加上这个前缀后如果指定位置不存在配置文件Spring Boot 不会报错而是继续用其他位置的配置。例如--spring.config.locationoptional:/etc/myapp/。不加optional:时配置文件缺失会直接导致启动失败。这个细节在写部署脚本时非常实用能避免因为少放了一个配置文件而让整个服务起不来的尴尬。4.3 指定 location 之后的 profile 行为指定 location 后再配合 profile有一个值得注意的点如果你指定的是一个目录激活 profile 后 Spring Boot 会在该目录下找application-{profile}.properties。但如果你指定的是一个具体文件比如--spring.config.location/etc/myapp/application.properties那么 profile 机制仍然会生效Spring Boot 会在同一目录下找application-{profile}.properties来加载。这个行为可能有点绕我举个例子说明。假设你执行java -jar myapp.jar --spring.config.location/etc/myapp/application.properties --spring.profiles.activeprodSpring Boot 会加载/etc/myapp/application.properties然后尝试加载/etc/myapp/application-prod.properties。如果后者存在则覆盖前者中的同名配置项如果不存在则仅加载前者。很多人在部署时发现配置文件没生效其实就是因为只指定了application.properties而生产环境的差异配置在application-prod.properties里那个文件又没被放到同一目录下。5. 方式三--spring.config.additional-location追加外部配置5.1 外部优先、内部兜底的最佳实践如果你希望 jar 包里的默认配置仍然生效只是用外部配置覆盖其中一部分那就要用--spring.config.additional-location。这个名字里的additional很关键——它是在默认加载路径之外追加额外的搜索位置而不是替换默认路径。java -jar myapp.jar --spring.config.additional-location/etc/myapp/执行这条命令后Spring Boot 的配置搜索路径变成默认位置jar 包内 classpath 和当前目录等加上/etc/myapp/。加载时外部位置的配置优先级更高会覆盖 jar 包内的同名配置项。这个特性非常契合外部配置优先的部署原则——你不需要维护一份完整的配置副本只需要在外部配置里放那些需要按环境变化的项数据库地址、密码、端口等其他配置继续用 jar 包内的默认值。5.2 多个位置之间的加载优先级当同时存在多个 additional-location 时优先级规则是Spring Boot 2.4 之前越靠前的优先级越高Spring Boot 2.4 之后越靠后的优先级越高。这个变化改得比较隐蔽我见过有同事升级 Spring Boot 版本后发现配置优先级颠倒排查了半天才发现是这个原因。以 Spring Boot 2.4 为例java -jar myapp.jar --spring.config.additional-location/etc/myapp/config/,/opt/myapp/override//opt/myapp/override/中的配置会覆盖/etc/myapp/config/中的同名配置项。这种顺序设计其实更符合直觉——追加的位置越靠后越像最后的覆盖层。5.3 与 profile 的组合使用场景--spring.config.additional-location和 profile 组合时推荐的做法是外部目录下放application.properties包含环境差异项然后按环境创建application-prod.properties、application-test.properties等文件。启动命令java -jar myapp.jar --spring.config.additional-location/etc/myapp/ --spring.profiles.activeprod这样加载顺序依次是jar 包内application.properties- jar 包内application-prod.properties- 外部/etc/myapp/application.properties- 外部/etc/myapp/application-prod.properties。后加载的覆盖先加载的最终生效的是外部配置里的生产环境值。我在实际项目里比较推荐这种组合它让本地开发用 jar 包内配置、服务器部署用外部配置覆盖成为可能而且不需要在打包时做任何 profile 相关的过滤处理。唯一的代价是需要在部署目录里维护一份配置文件但这本来就是部署工作的一部分。6. 方式四环境变量与SPRING_CONFIG_LOCATION6.1 环境变量的加载优先级和写法环境变量是另一种指定配置文件的方式适合 Docker 部署、Kubernetes Pod 环境变量注入这类场景。Spring Boot 支持通过环境变量SPRING_CONFIG_LOCATION来指定配置位置效果等同于--spring.config.location。export SPRING_CONFIG_LOCATION/etc/myapp/application.yml java -jar myapp.jar在 Docker 中则更简单ENV SPRING_CONFIG_LOCATION/etc/myapp/ CMD [java, -jar, myapp.jar]或者用docker run -edocker run -e SPRING_CONFIG_LOCATION/etc/myapp/ -p 8080:8080 myapp-image6.2 环境变量与命令行参数的优先级比较按照 Spring Boot 配置优先级规则命令行参数优先级高于环境变量。这意味着如果你同时设置了SPRING_CONFIG_LOCATION环境变量和--spring.config.location命令行参数命令行的值会覆盖环境变量。这个特性在设计部署系统时很有用环境变量作为默认值提供给所有实例但某个实例需要特殊配置时可以在启动命令里用命令行参数覆盖不需要改动环境变量或重新部署 Pod。6.3 环境变量的命名规则Spring Boot 的环境变量绑定有一个宽松规则环境变量名可以包含下划线或点号。SPRING_CONFIG_LOCATION对应spring.config.location这是官方文档明确支持的映射。但如果你自己定义某个配置项的环境变量比如server.port对应的环境变量是SERVER_PORTSpring Boot 会把环境变量名中的下划线替换成点号进行匹配。这个规则也会成为坑——如果你设置了一个名为MYAPP_DATABASE_URL的环境变量而配置项叫myapp.database-urlSpring Boot 并不能直接匹配上因为连字符减号和下划线的映射规则在不同版本中行为略有不同最稳妥的做法是让环境变量名和配置项名在去掉分隔符后保持一致。7. 几种方式的核心对比与选型建议7.1 一张表看懂差异方式语法示例是否替换默认搜索路径适用场景优先级profile 激活--spring.profiles.activeprod否多环境切分、同包多环境部署最高针对 profile 选择本身config.location--spring.config.location/etc/myapp/是完全自主控制配置来源配置完整性有保证高additional-location--spring.config.additional-location/etc/myapp/否追加外部配置覆盖内部默认值高环境变量SPRING_CONFIG_LOCATION/etc/myapp/视变量名而定Docker/K8s 环境注入中JVM 系统属性-Dspring.config.location...视属性名而定脚本启动、需与 JVM 参数统一管理中7.2 我的选型建议基于实际部署经验我给的选型逻辑很简单单机直接部署优先用--spring.profiles.active配合打包内的多环境配置文件。前提是你能保证多环境配置不包含敏感信息比如生产数据库密码或者敏感信息通过额外的环境变量注入。这是最轻量、最不容易出错的方式。配置文件必须放在 jar 包外用--spring.config.additional-location这样既保留了 jar 包内配置的兜底能力又能让运维直接修改外部文件而不用重新打包。配置完全由外部接管、jar 包内配置作废用--spring.config.location常用于安全要求高的场景——生产环境的完整配置只存在于受控目录jar 包内不放任何有效配置。容器化部署优先用环境变量SPRING_CONFIG_LOCATION或SPRING_PROFILES_ACTIVE这样 Docker Compose / K8s 的 YAML 里可以直接配置不需要在 CMD 里拼字符串。提示如果部署平台支持 ConfigMap 挂载K8s我强烈建议把配置挂载为文件然后通过--spring.config.additional-location/config/指向挂载目录。这样配置更新后只需要重启应用就能生效比把配置烧进镜像再重新构建要快得多。8. 实战一个部署脚本里配置指定的完整演进过程8.1 第一版裸奔的java -jar假设有一个标准的 Spring Boot 项目配置文件在src/main/resources/application.properties和application-prod.properties。一开始的部署脚本长这样#!/bin/bash java -jar myapp.jar这版脚本在开发环境用没问题但放到服务器上就会发现jar 包内配置连的是本地数据库日志级别是 DEBUG端口还是 8080——完全不是生产环境该有的样子。8.2 第二版加上 profile 激活#!/bin/bash export SPRING_PROFILES_ACTIVEprod java -jar myapp.jar这里用环境变量SPRING_PROFILES_ACTIVE而不是命令行参数是因为在 systemd service 文件或 supervisor 配置里环境变量的写法更直观也方便统一管理。如果要在命令行写等价的是java -jar myapp.jar --spring.profiles.activeprod这版能解决 80% 的问题。剩下的问题在于生产环境的数据库密码还是被打进了 jar 包内的application-prod.properties只要拿到 jar 包就能反编译看到这在安全审计时很难交代。8.3 第三版外部配置接管敏感项#!/bin/bash SPRING_PROFILES_ACTIVEprod SPRING_CONFIG_ADDITIONAL_LOCATION/etc/myapp/ java -jar myapp.jar于是我们在/etc/myapp/下放了一个application-prod.properties里面只写了敏感项spring.datasource.usernameprod_user spring.datasource.password${DB_PASSWORD}这里又出现一个技巧${DB_PASSWORD}是占位符Spring Boot 会从环境变量DB_PASSWORD中取值如果环境变量不存在则启动报错。这样密码就不落地在任何配置文件里只存在于服务器的环境变量中。这个模式在部署实践中非常实用相当于给配置加了一层动态解析能力。当然第三版仍然有改进空间。application-prod.properties这个文件因为是外部配置了按 additional-location 的规则它会覆盖 jar 包内同名文件但也意味着如果默认位置里的application-prod.properties还在 jar 包内反正它会被外部覆盖留着就是一份冗余。8.4 第四版Docker 环境变量版FROM openjdk:17-jdk-slim WORKDIR /app COPY target/myapp.jar . ENV SPRING_PROFILES_ACTIVEprod \ SPRING_CONFIG_ADDITIONAL_LOCATION/config/ VOLUME /config EXPOSE 8080 ENTRYPOINT [java, -jar, myapp.jar]运行时docker run -v /etc/myapp:/config -e DB_PASSWORDxxx myapp-image这版的好处是镜像里不包含任何环境的敏感配置不同环境测试、生产、灾备用同一个镜像通过挂载不同的配置目录实现环境隔离。这个思路在微服务多实例部署时能节省大量镜像构建时间——你只需要构建一次镜像剩下的差异全在配置挂载层。9. 实测中遇到的典型报错与排查过程9.1 启动报错No active profile set, falling back to 1 default profile这个 WARN 日志几乎每个 Spring Boot 项目启动时都会出现但它并不是错误只是提示你没有显式激活 profile。如果你看到这行日志说明 Spring Boot 认为你没有通过任何方式指定 profile应用将以默认配置即只加载application.properties启动。我在排查线上问题时遇到配置没生效的第一反应就是先看启动日志有没有这行警告。如果存在直接确认是不是环境变量SPRING_PROFILES_ACTIVE没传进去或者 systemd service 文件里 Environment 配置写错了。9.2 指定 location 后配置文件找不到Config data location file:/etc/myapp/ does not existSpring Boot 2.4 对配置位置存在性检查变得严格了。不加optional:前缀时指定的位置不存在就会报错。如果你希望位置不存在也正常启动需要改成java -jar myapp.jar --spring.config.additional-locationoptional:/etc/myapp/不过要小心加上optional:后如果位置确实不存在它会被静默跳过这可能导致你误以为配置加载了实际却没有。我的处理方式是部署脚本里先检查配置文件是否存在存在再启动不存在则打印警示并退出。自动化部署脚本中这种前置校验比让 Spring Boot 去处理更可控。9.3 最隐蔽的坑application.properties编码导致的中文乱码配置文件里的中文注释或中文属性值出现乱码问题是文件编码不是 UTF-8。java -jar启动时Spring Boot 默认按 UTF-8 读取 properties 文件从 Spring Boot 2.4 开始application.properties默认 UTF-8 读取但如果你的文件是用 GBK 保存的比如在 Windows 上用记事本编辑过就会乱码。解决方案是确保所有配置文件统一用 UTF-8 编码保存并且在编辑器的右下角确认编码格式。9.4 命令行参数被 shell 吞掉的经典案例写启动脚本时如果配置值包含了特殊字符比如密码里的、*、空格又没有给参数加引号shell 可能把参数拆分或解析成通配符。比如# 错误密码包含 会被 shell 解析为后台执行 java -jar myapp.jar --spring.datasource.passwordabc123 # 正确整个参数用单引号包裹 java -jar myapp.jar --spring.datasource.passwordabc123这种问题通常不会导致启动失败但密码会被截断应用连不上数据库时才暴露问题排查时容易被忽略。建议在脚本中对所有包含变量值的参数统一加双引号比如java -jar myapp.jar --spring.datasource.password${DB_PASSWORD}这一条看起来不起眼但在实际部署中救过我很多次。10. 关于配置文件优先级我还想多说的几个细节10.1 同一定义在不同位置的生效验证方法你可能会问我怎么确认最终加载到的是哪个配置Spring Boot 提供了多种方式验证。最简单的是启动时加--debug参数Spring Boot 会输出大量的自动配置报告其中包含条件评估信息但这份报告不会直接列出每个配置项的来源。更直接的方式是使用 Actuator 的configprops端点# 先确保 pom.xml 引入了 spring-boot-starter-actuator curl http://localhost:8080/actuator/configprops或者更直观地在启动命令里加一个 Spring Boot 支持的调试参数java -jar myapp.jar --debug --spring.profiles.activeprod但说实话--debug输出的信息量太大反而不好定位。我更推荐在代码里临时加一个ApplicationRunner打印关键配置Component public class ConfigPrinter implements ApplicationRunner { Value(${spring.datasource.url:unknown}) private String datasourceUrl; Override public void run(ApplicationArguments args) { System.out.println(当前数据源 URL: datasourceUrl); } }启动后看控制台输出一眼就知道最终加载的是哪份配置。这个方法写起来简单排查效率极高尤其适合快速验证外部配置是否真的覆盖了 jar 包内配置。当然记得在验证完把这段临时代码删掉。10.2 Spring Boot 2.4 前后的配置加载逻辑差异Spring Boot 2.4 是一个分水岭。2.4 之前配置加载顺序是先加载所有位置的配置再按优先级覆盖2.4 之后引入了spring.config.import机制和新的加载顺序且application.properties和application.yml同时存在时的行为也变了。如果你的项目从 2.3 升级到 2.4要特别留意spring.config.location的语义调整。2.4 之后多个 location 之间的优先级顺序变为后声明者优先后面配置覆盖前面配置同时optional:前缀成为标配写法。这些变化不会出现在升级文档的显眼位置但一旦你的启动参数用到了多个 location行为差异就非常明显。10.3 一个建议把配置指定写进项目 README我见过太多项目在 README 里只写mvn spring-boot:run启动完全没提生产环境怎么指定配置。结果换一个人来部署就靠猜。强烈建议在 README 里单独列一节部署配置说明至少包含三块内容每个环境对应的 profile 名称和配置文件位置生产环境部署时使用的启动命令含全部参数如果需要外部配置覆盖配置文件放在哪个目录、命名规则是什么。不要觉得这是多余的工作——等你在凌晨两点被电话叫起来排查为什么测试环境连了生产库的时候就知道一份清晰的部署说明有多值钱了。配置文件指定的方式本身不复杂但它是部署环节最容易出静默错误的地方也是团队协作中必须用文档锁死的知识。最后再分享一个小经验无论你用哪种方式指定配置文件都养成一个习惯——启动后第一件事看日志开头几行确认当前活跃的 profile 和配置来源。Spring Boot 在启动时会打印类似The following 1 profile is active: prod的日志看到这行再继续后续操作能避免一半以上的环境错乱问题。