为何Testcontainers未读取.testcontainers文件中的docker.host变量？

Testcontainers的配置文件不生效，大概率是以下几个原因导致的，逐个排查即可：

1. 配置文件名错误 #

Testcontainers默认读取的配置文件是**.testcontainers.properties**，不是你使用的.testcontainers。把文件名改成正确的后缀，放在用户主目录（~/.testcontainers.properties）或项目根目录下，才能被识别加载。

2. 配置优先级被覆盖 #

Testcontainers的配置加载优先级从高到低为：

• 系统环境变量（比如DOCKER_HOST）
• Java系统属性（比如启动时添加-Ddocker.host=xxx）
• 用户主目录下的.testcontainers.properties
• 项目根目录下的.testcontainers.properties

如果你的IntelliJ或构建工具（Gradle/Maven）里已经设置了DOCKER_HOST环境变量，或者在构建脚本里配置了对应的Java系统属性，配置文件里的docker.host会被直接覆盖。检查以下位置：

• IntelliJ的Run/Debug配置：查看「Environment variables」里是否存在DOCKER_HOST
• Gradle的build.gradle：是否有类似test { systemProperty 'docker.host', 'xxx' }的配置
• Maven的pom.xml：是否在maven-surefire-plugin里设置argLine参数包含-Ddocker.host=xxx

3. 配置文件格式或键名错误 #

确保配置文件里的键名是**docker.host**，格式为标准的properties键值对：

docker.host=tcp://your-remote-docker-host:2375

注意不要添加多余的空格或引号，否则会被当作值的一部分处理。

4. 权限或加载路径问题 #

• Linux下如果用sudo运行测试，Testcontainers会读取root用户的配置文件（/root/.testcontainers.properties），而非当前用户的~/.testcontainers.properties，避免用sudo执行测试。
• 检查配置文件的读取权限：执行ls -l ~/.testcontainers.properties确认当前用户拥有读取权限。

5. 验证配置是否被加载 #

在测试代码里添加一行调试代码，打印Testcontainers实际读取的配置：

import org.testcontainers.TestcontainersConfiguration;

// 在测试类的@BeforeAll或初始化方法中添加
System.out.println("Testcontainers Docker Host: " + TestcontainersConfiguration.getInstance().getDockerHost());

运行测试后查看控制台输出，就能明确配置文件的设置是否生效。如果输出仍是本地Podman地址，说明配置文件未被加载，回到前面的步骤重新排查。

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