Testcontainers在C#中需装DotNet.Testcontainers包、依赖Docker daemon且要求.NET 6+，必须显式调用StartAsync/StopAsync；装错包、环境未就绪或路径非绝对导致95%失败。
Testcontainers 在 C# 中不是“装上就能跑”的库，它依赖 Docker daemon、要求 .NET 6+、必须显式管理生命周期——跳过任一环节，StartAsync() 就会直接抛 DockerException 或静默失败。
装错 NuGet 包是第一道坎
搜索 “Testcontainers” 会列出多个包，但只有 DotNet.Testcontainers 是核心实现。装错会导致编译通过、运行时报 TypeLoadException 或找不到 MsSqlBuilder 等类型。
-
Testcontainers（无前缀）：已废弃，不兼容 .NET 6+，别碰 -
Testcontainers.Xunit：只提供 xUnit 生命周期集成，不包含容器启动逻辑，不能单独用 -
DotNet.Testcontainers：唯一必须安装的包，命令是dotnet add package DotNet.Testcontainers
容器启动失败，95% 是环境没就绪
await container.StartAsync() 报 NotFound 或 DockerException，几乎从不怪代码——而是 Docker daemon 不可达。
- 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” - GitHub Actions：不能只写
services，必须显式声明docker://docker:dind或用setup-docker-action
挂载文件路径必须绝对，且要适配 CI 工作目录
WithBindMount("config.json", "/app/config.json") 在本地可能“看起来”能跑，但在 CI 中必然失败——因为第一个参数是相对路径，GetFullPath 会解析成 runner 根目录而非项目路径。
- 正确写法：
WithBindMount(Path.Combine(AppContext.BaseDirectory, "..", "..", "test-data", "config.json"), "/app/config.json") - Windows 下避免反斜杠：
Path.AltDirectorySeparatorChar替代\，或统一用/ - 目标路径别写成
/config.json，优先用语义化路径如/app/config/，防止覆盖容器系统文件
SQL Server 容器必须设非空密码，且别硬写端口
MsSqlContainer 启动失败最常见的原因是空密码或固定端口绑定。SQL Server 镜像强制要求密码，且 Testcontainers 会自动分配可用端口——硬写 1433 会导致并行测试冲突。
- 必须调用
.WithPassword("Strong_password_123!")，空字符串或 null 直接失败 - 镜像标签建议显式指定，例如
mcr.microsoft.com/mssql/server:2022-latest，避免拉取latest导致 CI 行为漂移 - 连接串必须用
dbContainer.GetConnectionString()获取，它已含动态分配的 host 和 port，host 在 .NET SDK 8+ 默认为容器名，CI 中若需访问宿主机服务，用host.docker.internal（Linux/macOS 需手动映射）
最易被忽略的是生命周期管理：不显式调用 StopAsync()，容器会在后台持续运行，下次测试可能因端口占用或数据残留而失败；xUnit 中应实现 IAsyncLifetime，而不是靠 IDisposable 或析构函数。
