Testcontainers在C#中需用DotNet.Testcontainers包，非官方且.NET 6+才支持；环境须Docker Desktop运行或Linux用户加入docker组；文件挂载路径必须绝对，SQL Server容器必须设非空密码，生命周期须显式调用StartAsync/StopAsync。
Testcontainers 在 C# 中不是开箱即用的官方库，必须用 DotNet.Testcontainers，装错包、环境没就绪、路径写错——这三类问题占了 80% 的失败案例。
装对包：DotNet.Testcontainers 而不是 Testcontainers
社区库名和 NuGet 包名不一致，这是最常踩的第一坑。NuGet 搜索 “Testcontainers” 会列出多个结果，但只有 DotNet.Testcontainers 是核心实现；Testcontainers.Xunit 只提供 xUnit 生命周期集成，不包含容器启动逻辑；Testcontainers（无前缀）早已废弃且不兼容 .NET 6+。
- 正确安装命令：
dotnet add package DotNet.Testcontainers - 必须引用该包才能调用
MsSqlBuilder、PostgreSqlBuilder等类型 - .NET Framework 不支持，最低要求是 .NET 6
启动前必查：Docker daemon 是否真正可用
await container.StartAsync() 抛 DockerException 或 NotFound 错误，95% 不是代码问题，而是 Docker 环境未就绪。
- Windows/macOS：Docker Desktop 必须运行中，且勾选 “Start Docker Desktop when you log in”
- Linux/WSL2：确认当前用户在
docker组，执行docker info应返回有效 JSON；WSL2 用户还需在 Docker Desktop 设置中启用 “Use the WSL 2 based engine” - CI 场景（如 GitHub Actions）：不能只写
services，必须显式声明docker://docker:dind或使用setup-docker-action
挂载文件时路径必须绝对，且需适配 CI 工作目录
WithBindMount("config.json", "/app/config.json") 在本地可能“碰巧”工作，但在 CI 中必然失败——因为第一个参数是相对路径，GetFullPath 会解析成 runner 根目录而非项目 checkout 路径。
- 正确写法：
WithBindMount(Path.Combine(AppContext.BaseDirectory, "..", "..", "test-data", "config.json"), "/app/config.json") - Windows 下注意路径分隔符：统一用
/或Path.AltDirectorySeparatorChar，避免反斜杠被 Docker 解析为转义 - 挂载目标路径别写成
/config.json，优先用语义化路径如/app/config/，防止覆盖容器系统文件
SQL Server 容器必须设密码，且别硬写端口
MsSqlContainer 启动失败最常见的原因是空密码或依赖固定端口 1433。
- SQL Server 镜像强制要求非空密码：
.WithPassword("Strong_password_123!")，传空字符串或省略会直接初始化失败 - 镜像标签建议显式指定，例如
mcr.microsoft.com/mssql/server:2022-latest，避免拉取latest导致 CI 环境行为漂移 - 别写
.WithExposedPorts(1433)—— Testcontainers 自动分配宿主机端口，连接一律用dbContainer.GetConnectionString()获取，其中 host 默认是host.docker.internal（CI 中需换为172.17.0.1）
最易被忽略的是生命周期管理：IDisposable.Dispose() 不 await，资源泄漏和端口冲突都源于此。务必用 IAsyncLifetime 或 await container.StopAsync() 显式终止，而不是靠 GC 或 using 块。
