Spring Boot应用中MONGO_CLUSTER环境变量加载失败问题排查

问题根源 #

spring-dotenv的环境变量加载时机晚于Spring Boot自动配置MongoDB客户端的时机，导致application.properties里的${MONGO_CLUSTER}还没被替换成实际值，就被MongoDB驱动解析，自然会报主机名格式错误。

解决方案 #

方案1：确保spring-dotenv在启动最早期加载 #

首先确认你的pom.xml里spring-dotenv依赖是较新版本（比如2.2.0+），旧版本可能存在加载顺序问题：

<dependency>
    <groupId>me.paulschwarz</groupId>
    <artifactId>spring-dotenv</artifactId>
    <version>2.2.0</version>
</dependency>

然后在application.properties里添加强制启用dotenv的配置，确保它优先加载：

spring.dotenv.enabled=true
spring.dotenv.path=.env # 确认路径正确，默认是项目根目录的.env

另外，检查你的.env文件里MONGO_CLUSTER的拼写是否完全一致（大小写敏感），比如：

MONGO_CLUSTER=cluster0.example.mongodb.net

方案2：改用编程式配置MongoClient #

绕过Spring自动配置的时机问题，自己手动读取环境变量并构建Mongo连接URI：

1. 先在application.properties里去掉原来的Mongo URI配置，换成单独的变量占位：

# 删掉原来的spring.data.mongodb.uri配置
mongo.cluster=${MONGO_CLUSTER}
mongo.database=your-db-name
mongo.username=your-username
mongo.password=your-password

2. 创建Mongo配置类，手动构建客户端：

import com.mongodb.client.MongoClient;
import com.mongodb.client.MongoClients;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class MongoConfig {

    @Value("${mongo.cluster}")
    private String mongoCluster;

    @Value("${mongo.database}")
    private String mongoDatabase;

    @Value("${mongo.username}")
    private String mongoUsername;

    @Value("${mongo.password}")
    private String mongoPassword;

    @Bean
    public MongoClient mongoClient() {
        String uri = String.format("mongodb+srv://%s:%s@%s/%s?retryWrites=true&w=majority",
                mongoUsername, mongoPassword, mongoCluster, mongoDatabase);
        return MongoClients.create(uri);
    }
}

这样就能确保环境变量已经被spring-dotenv加载后，再构建连接URI，避免解析占位符的问题。

方案3：使用Spring Boot原生@PropertySource加载.env #

如果spring-dotenv还是有问题，可以直接用Spring原生的@PropertySource加载.env文件（需要Spring Boot 2.4+）：

1. 确保已引入基础starter依赖：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter</artifactId>
</dependency>

2. 在启动类上添加注解：

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.PropertySource;

@SpringBootApplication
// .env在项目根目录用file:.env，在resources下用classpath:.env
@PropertySource(value = "file:.env", ignoreResourceNotFound = true)
public class YourApplication {
    public static void main(String[] args) {
        SpringApplication.run(YourApplication.class, args);
    }
}

之后application.properties里的${MONGO_CLUSTER}就能正常被替换了。

验证步骤 #

1. 启动前可以通过@Value注入MONGO_CLUSTER并打印，确认变量已成功加载；
2. 启动应用，检查Mongo客户端是否正常连接。

内容的提问来源于stack exchange，提问作者mercifulsamurai142