Spring Boot 配置文件怎么写

最后更新：2026-08-17
适用场景：Spring Boot 配置文件、application.yml、application.properties、多环境配置、server.port、spring.datasource、配置不生效排查

刚开始写 Spring Boot 项目时，很多问题其实不是 Controller、Service 写错了，而是配置文件没写对。

比如端口改了没生效、数据库连不上、application-dev.yml 没被读取、线上还是用了本地配置，这些都很常见。Spring Boot 的配置能力很灵活，但灵活也意味着：如果一开始没有约定好写法，后面很容易乱。

这篇文章不讲太多概念，直接按实际项目里最常用的方式整理。

一、先看结论

新项目建议优先使用 application.yml。

如果团队已经习惯 application.properties，继续用也没问题，但不要在同一个位置同时维护两套配置。Spring Boot 官方文档也建议一个项目尽量坚持使用一种格式；如果同一个位置同时存在 .properties 和 YAML 配置，.properties 会优先。

普通项目可以按这个结构放：

src/main/resources/
├── application.yml
├── application-dev.yml
├── application-test.yml
└── application-prod.yml

建议这样分工：

application.yml：放通用配置
application-dev.yml：本地开发配置
application-test.yml：测试环境配置
application-prod.yml：生产环境配置

生产环境不要把数据库密码、密钥、Token 直接写死在 Git 仓库里。更稳的做法是用环境变量、启动参数，或者服务器上的外部配置文件覆盖。

二、Spring Boot 会从哪里读取配置

最常见的位置是：

src/main/resources/application.yml

项目打包后，这个文件会进入 jar 包。Spring Boot 启动时会自动读取它。

除了 jar 包里的配置，Spring Boot 也支持外部配置文件、环境变量、Java 系统属性、命令行参数。实际项目里经常用命令行参数临时覆盖配置，比如：

java -jar demo.jar --server.port=9090

这时候即使 application.yml 里写的是：

server:
  port: 8080

最终项目还是会跑在 9090 端口。

记住一个实用判断：启动参数和环境变量通常比配置文件更适合做运行环境覆盖。不要为了部署到生产环境，专门改一版代码或者改一版 jar 包。

三、application.yml 怎么写

application.yml 适合写层级比较清楚的配置。比如一个常见的 Spring Boot Web 项目，可以这样写：

spring:
  application:
    name: demo-api

server:
  port: 8080

logging:
  level:
    root: info
    com.example.demo: debug

如果项目要连接 MySQL，可以继续加：

spring:
  application:
    name: demo-api

  datasource:
    url: jdbc:mysql://localhost:3306/demo?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai
    username: root
    password: 123456
    driver-class-name: com.mysql.cj.jdbc.Driver

server:
  port: 8080

这里有几个容易踩坑的点：

YAML 靠缩进表示层级，不要用 Tab
冒号后面通常要有空格
密码里如果有 #、:、@ 这类字符，建议加引号
不要把 spring.datasource.url 写到 server 下面

例如密码包含特殊字符时，建议这样写：

spring:
  datasource:
    password: "abc#123:456"

不要这样写：

spring:
  datasource:
    password: abc#123:456

这类问题有时不会一眼报得很清楚，但启动后数据库连接就是不对。

四、application.properties 怎么写

application.properties 是另一种写法，本质上也是配置同一批属性。

上面的 YAML 配置，换成 properties 大概是这样：

spring.application.name=demo-api

server.port=8080

logging.level.root=info
logging.level.com.example.demo=debug

spring.datasource.url=jdbc:mysql://localhost:3306/demo?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai
spring.datasource.username=root
spring.datasource.password=123456
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver

它的优点是简单直接，一行一个配置，不太容易因为缩进出错。

它的缺点是层级多了以后会比较长，比如 spring.datasource.hikari.maximum-pool-size、management.endpoints.web.exposure.include 这类配置，看起来没有 YAML 清楚。

所以我的建议是：

新项目：优先 application.yml
老项目：保持原来的 application.properties
团队项目：统一一种格式，不要每个人按自己喜好来

五、多环境配置怎么写

真实项目一般至少有两个环境：本地开发和生产环境。

可以先在 application.yml 写通用配置：

spring:
  application:
    name: demo-api

server:
  port: 8080

本地开发配置写到 application-dev.yml：

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/demo_dev?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai
    username: root
    password: 123456
    driver-class-name: com.mysql.cj.jdbc.Driver

logging:
  level:
    com.example.demo: debug

生产环境配置写到 application-prod.yml：

spring:
  datasource:
    url: jdbc:mysql://mysql-prod:3306/demo_prod?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai
    username: demo_user
    password: ${DB_PASSWORD}
    driver-class-name: com.mysql.cj.jdbc.Driver

logging:
  level:
    root: warn
    com.example.demo: info

注意这里的：

password: ${DB_PASSWORD}

意思是从环境变量 DB_PASSWORD 读取密码。这样生产密码就不用写进代码仓库。

启动时指定环境：

java -jar demo.jar --spring.profiles.active=prod

Linux 也可以这样：

SPRING_PROFILES_ACTIVE=prod java -jar demo.jar

Windows PowerShell 可以这样：

$env:SPRING_PROFILES_ACTIVE="prod"
java -jar demo.jar

如果你用 Docker Compose，可以这样传：

services:
  demo-api:
    image: demo-api:latest
    environment:
      SPRING_PROFILES_ACTIVE: prod
      DB_PASSWORD: "你的生产数据库密码"

不建议在 application.yml 里长期写死：

spring:
  profiles:
    active: prod

这样很容易出现本地、测试、生产混用配置的问题。生产环境应该由部署环境明确指定 profile。

六、server.port 怎么配置

改端口最常见：

server:
  port: 8081

或者：

server.port=8081

临时启动时可以直接覆盖：

java -jar demo.jar --server.port=9090

环境变量也可以：

SERVER_PORT=9090 java -jar demo.jar

如果你遇到 Port 8080 was already in use，不要一上来就改业务代码。先确认到底是谁占用了端口，再决定是杀进程还是换端口。

可以继续看：Spring Boot 端口被占用怎么处理

七、spring.datasource 怎么配置

Spring Boot 连接 MySQL 时，最少要确认这几件事：

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/demo?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai
    username: root
    password: 123456
    driver-class-name: com.mysql.cj.jdbc.Driver

还要确认项目里有 MySQL 驱动依赖：

<dependency>
    <groupId>com.mysql</groupId>
    <artifactId>mysql-connector-j</artifactId>
    <scope>runtime</scope>
</dependency>

如果你用了 Spring Boot 的依赖管理，一般不需要自己手动指定 MySQL 驱动版本，避免和 Spring Boot 管理的版本打架。

常见报错包括：

Failed to configure a DataSource
url attribute is not specified
Failed to determine a suitable driver class
Access denied for user
Communications link failure

这些不一定是代码问题，很多时候就是配置、依赖、数据库地址或账号密码没对上。

详细排查可以看：Spring Boot DataSource 报错怎么处理

八、自定义配置怎么读取

业务里经常会有自己的配置，比如上传路径、开关、第三方接口地址。

可以先在配置文件里写：

app:
  upload:
    path: /data/demo/upload
    max-size: 20MB
  feature:
    enable-cache: true

如果只是读一个值，可以用 @Value：

@Value("${app.upload.path}")
private String uploadPath;

但如果配置项比较多，更建议用 @ConfigurationProperties：

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;

@Component
@ConfigurationProperties(prefix = "app.upload")
public class UploadProperties {

    private String path;
    private String maxSize;

    public String getPath() {
        return path;
    }

    public void setPath(String path) {
        this.path = path;
    }

    public String getMaxSize() {
        return maxSize;
    }

    public void setMaxSize(String maxSize) {
        this.maxSize = maxSize;
    }
}

这种方式比到处写 @Value 更适合中大型项目，后面配置多了也更好维护。

九、配置不生效怎么排查

Spring Boot 配置不生效，先别急着改代码，按这个顺序查。

1. 文件名是不是写错了

正确：

application.yml
application.properties
application-dev.yml
application-prod.yml

常见错误：

applications.yml
applicaiton.yml
application-dev.yaml.txt

尤其是 Windows 下，注意不要被隐藏扩展名坑了。

2. 文件位置是不是对的

Maven / Gradle 项目通常放这里：

src/main/resources/application.yml

不要放到：

src/main/java

也不要放到随便一个普通目录里，除非你明确通过 spring.config.location 或 spring.config.additional-location 指定了外部配置路径。

3. YAML 缩进是不是错了

错误示例：

spring:
datasource:
  url: jdbc:mysql://localhost:3306/demo

正确示例：

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/demo

YAML 对缩进很敏感。少两个空格，意思就变了。

4. profile 有没有真的激活

如果你写了 application-prod.yml，但没有激活 prod，它不会按你想的方式生效。

启动时看日志里有没有类似 active profile 的信息，也可以直接指定：

java -jar demo.jar --spring.profiles.active=prod

5. 是否被启动参数或环境变量覆盖了

比如配置文件里写：

server:
  port: 8080

但启动命令里写：

java -jar demo.jar --server.port=9090

最终就是 9090。

环境变量也一样：

SERVER_PORT=9090 java -jar demo.jar

排查时不要只盯着 application.yml，也要看启动脚本、Docker Compose、Kubernetes 配置、1Panel 环境变量。

6. jar 包是不是旧的

本地改了配置，不代表服务器上的 jar 已经更新。

建议部署前确认：

mvn clean package

或者：

./gradlew clean build

然后确认上传和启动的是最新构建出来的 jar。

7. 同时存在 properties 和 yml

如果同一个位置同时有：

application.properties
application.yml

排查时会很麻烦。官方文档说明，同一位置下 .properties 优先级高于 YAML。

实际项目里更建议二选一，删掉不用的那份。

8. 用 Actuator 看实际配置

如果项目已经接入 Spring Boot Actuator，可以用 env、configprops 这类端点辅助排查。

不过生产环境不要随便开放这些端点，尤其是可能暴露环境变量、数据库地址、密钥相关信息。

常见坑

第一个坑：把生产密码写进 Git。

这件事短期省事，长期很危险。生产密码、云服务密钥、短信接口 Token、支付密钥，都不应该直接提交到仓库。

第二个坑：用代码判断环境。

不建议在业务代码里大量写：

if ("prod".equals(env)) {
    // ...
}

能用配置解决的，就尽量用配置解决。代码应该少关心自己跑在哪个环境。

第三个坑：为了上线临时改 application.yml。

比如上线前把本地数据库地址改成生产数据库地址，然后打包。这样很容易出事故。更推荐同一个 jar 包，通过 profile、环境变量或外部配置决定运行环境。

第四个坑：配置文件越写越大。

如果所有东西都堆到一个 application.yml，后面会很难维护。数据库、Redis、日志、第三方服务、自定义业务配置，最好按层级整理清楚，名字也要统一。

排查清单

配置不生效时，可以按下面清单查：

1. 文件名是否是 application.yml / application.properties
2. 文件是否放在 src/main/resources
3. YAML 缩进是否正确
4. 是否混用了 application.yml 和 application.properties
5. active profile 是否正确
6. application-dev.yml / application-prod.yml 是否存在
7. 启动参数是否覆盖了配置
8. 环境变量是否覆盖了配置
9. Docker / 1Panel / Kubernetes 是否传了环境变量
10. jar 包是否重新打包并部署
11. 数据库地址、账号、密码是否对应当前环境
12. MySQL 驱动依赖是否存在
13. 是否可以通过日志、Actuator env、configprops 查到最终值

常见问题 FAQ

1. application.yml 和 application.properties 用哪个？

新项目建议用 application.yml，层级更清楚。老项目如果已经用 application.properties，继续保持也可以。

关键不是哪种更高级，而是项目里要统一。

2. 两个文件可以同时存在吗？

可以存在，但不建议。

如果同一个位置同时存在 .properties 和 YAML，.properties 会优先。排查问题时很容易以为改了 application.yml，实际上生效的是 application.properties。

3. application-dev.yml 为什么不生效？

通常是没有激活 dev。

启动时指定：

java -jar demo.jar --spring.profiles.active=dev

或者在本地开发时临时设置环境变量：

SPRING_PROFILES_ACTIVE=dev java -jar demo.jar

4. 生产环境密码应该写在哪里？

不建议写进 Git 仓库。

常见做法是环境变量：

spring:
  datasource:
    password: ${DB_PASSWORD}

部署时再设置：

DB_PASSWORD=真实密码

5. server.port 配了为什么没生效？

先查启动命令和环境变量。

如果启动命令里带了：

--server.port=9090

或者环境变量里有：

SERVER_PORT=9090

它们可能会覆盖配置文件里的端口。

6. spring.datasource 配了还是报错怎么办？

先确认四件事：

spring.datasource.url 是否正确
username / password 是否正确
MySQL 服务是否能连通
项目里是否有 MySQL 驱动依赖

如果还是不行，看这篇：Spring Boot DataSource 报错怎么处理

7. YAML 里的数字和密码要不要加引号？

普通数字不用。

但密码、Token、包含特殊字符的字符串，建议加引号。比如：

password: "abc#123:456"

这样更稳，避免被 YAML 解析成别的含义。

最后总结

Spring Boot 配置文件不用写得复杂。

大多数项目按这个思路就够了：

通用配置放 application.yml
本地配置放 application-dev.yml
生产配置放 application-prod.yml
生产密码用环境变量
临时覆盖用启动参数
排查问题先看 profile 和覆盖顺序

配置文件的目标不是“看起来高级”，而是让项目在不同环境下稳定启动、容易排查、不容易误连生产库。

参考资料

Spring Boot 官方文档：Externalized Configuration

Spring Boot 官方文档：Profiles

Spring Boot 官方文档：Common Application Properties

更新记录

2026-08-17：
- 创建文章《Spring Boot 配置文件怎么写》
- 增加 application.yml 和 application.properties 示例
- 增加 dev / test / prod 多环境配置说明
- 增加 server.port、spring.datasource、环境变量覆盖示例
- 增加配置不生效排查清单和 FAQ

如果觉得文章对你有用，请随意赞赏

SpringBoot 环境配置

Spring Boot 配置文件怎么写

https://java.li/archives/spring-boot-config-file

作者

HiF

发布于

2026-08-17

更新于

2026-08-17

许可协议

CC BY 4.0

Json美化工具站	文字推荐位2
yq.cx \| 一起查询	文字推荐位4
文字推荐位5	文字推荐位6
文字推荐位7	文字推荐位8
文字推荐位9	文字推荐位10

Spring Boot 配置文件怎么写

Spring Boot 配置文件怎么写

一、先看结论

二、Spring Boot 会从哪里读取配置

三、application.yml 怎么写

四、application.properties 怎么写

五、多环境配置怎么写

六、server.port 怎么配置

七、spring.datasource 怎么配置

八、自定义配置怎么读取

九、配置不生效怎么排查

1. 文件名是不是写错了

2. 文件位置是不是对的

3. YAML 缩进是不是错了

4. profile 有没有真的激活

5. 是否被启动参数或环境变量覆盖了

6. jar 包是不是旧的

7. 同时存在 properties 和 yml

8. 用 Actuator 看实际配置

常见坑

排查清单

常见问题 FAQ

1. application.yml 和 application.properties 用哪个？

2. 两个文件可以同时存在吗？

3. application-dev.yml 为什么不生效？

4. 生产环境密码应该写在哪里？

5. server.port 配了为什么没生效？

6. spring.datasource 配了还是报错怎么办？

7. YAML 里的数字和密码要不要加引号？

最后总结

相关文章

参考资料

更新记录

作者

发布于

更新于

许可协议

评论