Testcontainers for .NET容器创建无提示，启动抛出DockerAPIException

问题重现 #

使用Testcontainers 2.3.0编写xUnit集成测试启动SQL Server容器时，调用container.StartAsync()抛出Docker.DotNet.DockerApiException，提示容器未运行，但Docker Desktop中可看到对应ID的容器，测试结束后容器自动移除。

原因及解决办法 #

1. 密码不符合SQL Server容器复杂度要求

SQL Server官方镜像强制要求密码满足至少8字符，包含大写、小写、数字、特殊字符中的三种。你使用的password过于简单，会导致容器启动失败，Testcontainers在重试或状态校验时触发冲突异常。

修改代码中的密码配置为符合要求的字符串：

var container = new TestcontainersBuilder<MsSqlTestcontainer>()
    .WithDatabase(new MsSqlTestcontainerConfiguration
    {
        Password = "Passw0rd!", // 符合复杂度要求的密码
    })
    .Build();

2. 显式指定SQL Server镜像版本及必要环境变量

部分版本的Testcontainers可能未默认配置完整的启动参数，显式指定镜像版本并添加ACCEPT_EULA=Y环境变量可避免启动异常：

var container = new TestcontainersBuilder<MsSqlTestcontainer>()
    .WithImage("mcr.microsoft.com/mssql/server:2022-latest") // 指定稳定镜像版本
    .WithDatabase(new MsSqlTestcontainerConfiguration
    {
        Password = "Passw0rd!",
    })
    .WithEnvironment("ACCEPT_EULA", "Y") // 显式同意SQL Server许可协议
    .Build();

3. 增加Docker资源分配

SQL Server容器启动至少需要2GB内存，若Docker分配的内存不足，容器会启动后立刻退出，导致Testcontainers检测到状态异常。

• 打开Docker Desktop → 设置 → 资源 → 高级
• 将内存分配调整为2GB及以上

4. 添加容器健康检查等待

容器启动需要一定时间完成初始化，显式添加健康检查等待可确保容器完全就绪后再进行连接：

var container = new TestcontainersBuilder<MsSqlTestcontainer>()
    .WithDatabase(new MsSqlTestcontainerConfiguration
    {
        Password = "Passw0rd!",
    })
    .WaitUntilContainerIsHealthy() // 等待容器进入健康状态
    .Build();

排查辅助步骤 #

如果问题仍存在，可查看Docker容器日志定位具体原因：

1. 在Docker Desktop中找到异常对应的容器
2. 进入容器详情页查看日志，通常会明确提示启动失败的原因（如密码不合法、资源不足等）

内容的提问来源于stack exchange，提问作者Petr Nečas