在Quarkus中使用Testcontainers时Docker环境无效错误的解决方法

针对你遇到的Could not find a valid Docker environment错误，结合Quarkus 2.16.4.Final、Corretto 17和Testcontainers 1.18.0的环境，下面是具体的排查和解决步骤：

1. 确保Docker环境的可访问性 #

• 先通过终端执行docker ps验证Docker daemon是否正常运行，当前用户是否有Docker访问权限（Linux用户需确认在docker用户组）。
• 若使用Docker Desktop，检查是否开启了Expose daemon on tcp://localhost:2375 without TLS（Windows/macOS），或Unix Socket的权限是否正确。

2. 显式配置Testcontainers的Docker策略 #

Quarkus测试环境可能会隔离系统环境变量，导致Testcontainers无法自动检测Docker环境，可通过以下方式强制指定：

方式一：通过配置文件指定 #

在src/test/resources/application-test.properties中添加：

# Unix系统（Linux/macOS）用这个策略
testcontainers.docker.client.strategy=org.testcontainers.dockerclient.UnixSocketClientProviderStrategy
# Windows系统用TCP策略
# testcontainers.docker.client.strategy=org.testcontainers.dockerclient.TcpSocketClientProviderStrategy
testcontainers.host.docker.internal=localhost

方式二：在TestResource中设置系统属性 #

修改你实现的QuarkusTestResourceLifecycleManager，在启动容器前显式设置系统属性：

import io.quarkus.test.common.QuarkusTestResourceLifecycleManager;
import org.testcontainers.containers.PostgreSQLContainer;
import java.util.Map;

public class PostgresTestResource implements QuarkusTestResourceLifecycleManager {
    private PostgreSQLContainer<?> postgres;

    @Override
    public Map<String, String> start() {
        // 强制指定Docker客户端策略
        System.setProperty("testcontainers.docker.client.strategy", 
            "org.testcontainers.dockerclient.UnixSocketClientProviderStrategy");
            
        postgres = new PostgreSQLContainer<>("postgres:14-alpine")
                .withDatabaseName("testdb")
                .withUsername("test")
                .withPassword("test");
        postgres.start();
        
        return Map.of(
                "quarkus.datasource.jdbc.url", postgres.getJdbcUrl(),
                "quarkus.datasource.username", postgres.getUsername(),
                "quarkus.datasource.password", postgres.getPassword(),
                "quarkus.datasource.db-kind", "postgresql"
        );
    }

    @Override
    public void stop() {
        if (postgres != null) postgres.stop();
    }
}

3. 检查依赖配置与类加载 #

确保Testcontainers的依赖在测试 scope 中正确引入，且未被Quarkus类加载器排除：
Maven示例（pom.xml）：

<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>postgresql</artifactId>
    <version>1.18.0</version>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>testcontainers</artifactId>
    <version>1.18.0</version>
    <scope>test</scope>
</dependency>

4. 验证版本兼容性 #

Quarkus 2.16.x系列官方推荐的Testcontainers版本为1.17.x~1.18.x，若问题仍存在，可尝试将Testcontainers降级到1.17.6，部分版本在Quarkus环境下存在兼容性问题。

测试类注解示例 #

确保测试类正确绑定TestResource：

import io.quarkus.test.junit.QuarkusTest;
import io.quarkus.test.common.QuarkusTestResource;
import org.junit.jupiter.api.Test;

@QuarkusTest
@QuarkusTestResource(PostgresTestResource.class)
public class SampleResourceTest {
    @Test
    public void testSampleEndpoint() {
        // 你的测试逻辑
    }
}

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