Testcontainers for .NET 是用于在 C# 单元测试中按需启动、管理并销毁真实 Docker 容器的测试辅助库，依赖本地 Docker daemon，不替代 docker build/run；核心用途是提供真实依赖（如 SQL Server、MongoDB）供集成测试，确保环境一致性与隔离性。
Testcontainers 在 C# 中不是“创建容器”的工具，而是按需启动、管理并销毁真实 Docker 容器的测试辅助库。它不替代 docker build 或 docker run，而是帮你把容器当“测试依赖”用——比如启动一个真实的 PostgreSQL 实例，而不是 mock 一个连接字符串。
用 MsSqlContainer 启动 SQL Server 测试实例
最常见场景：验证 EF Core 数据访问逻辑是否在真实 SQL Server 上行为正确。
关键点：
-
MsSqlContainer必须配合WithPassword("...")使用，SQL Server 镜像拒绝空密码 - 镜像标签建议显式指定，避免拉取
latest导致 CI 环境不可控（例如用mcr.microsoft.com/mssql/server:2022-latest） - 容器端口映射由 Testcontainers 自动分配，别硬写
:1433；用dbContainer.GetConnectionString()拿连接字符串 - 若本地 Docker Desktop 未运行，
await dbContainer.StartAsync()会直接抛DockerException，建议在 CI 中加前置检查
示例片段：
var dbContainer = new MsSqlBuilder()
.WithImage("mcr.microsoft.com/mssql/server:2022-latest")
.WithPassword("Strong_password_123!")
.Build();
<p>await dbContainer.StartAsync(); // 启动后才可获取连接串
var connectionString = dbContainer.GetConnectionString();
</p>
文件挂载必须用 WithBindMount()，且路径要绝对
想让容器读取本地 data/config.json？别直接传相对路径——WithBindMount("data/config.json", "/app/config.json") 在 CI 中大概率失败。
原因和对策：
-
WithBindMount()第一个参数必须是宿主机绝对路径，否则 Windows 下静默失败，Linux 下报FileNotFoundException - 用
Path.GetFullPath("data/config.json")转换，但注意：CI 工作目录（如 GitHub Actions 的/home/runner/work/repo/repo）可能与你本地不同 - 推荐在测试项目根目录放
test-data/，并在.gitignore中排除敏感内容，再统一用Path.Combine(AppContext.BaseDirectory, "..", "..", "test-data")构建路径 - 容器内目标路径避免写成
/config.json，优先用语义化路径如/app/config/，防止覆盖系统文件
权限问题：Linux 容器里读不到挂载的文件？先看 UID
现象：System.UnauthorizedAccessException: Access to the path '/app/config/appsettings.json' is denied，但文件明明存在。
根本原因：
- Docker on Linux 默认以 root 运行容器进程，但挂载进来的文件属主是 CI runner 用户（UID=1001），root 进程无权读取非 644 权限的文件
- Windows/macOS Docker Desktop 有 UID 映射层，但行为不稳定，跨平台测试时不能依赖
可靠解法：
- 对 Alpine 基础镜像，在
Dockerfile中预建用户：RUN addgroup -g 1001 -f appgroup && adduser -S appuser -u 1001，然后用WithUser("appuser") - 或在容器启动命令中补 chmod：
WithCommand("sh", "-c", "chmod 644 /app/config/* && exec dotnet MyApp.dll") - 别指望
WithBindMount()自动处理权限——它只做路径映射
测试类生命周期必须实现 IAsyncLifetime
很多人用 [Fact] + 手动 StartAsync()/StopAsync()，结果容器没等启动完就执行测试，或没清理干净导致端口占用。
XUnit 正确姿势：
- 定义 fixture 类实现
IAsyncLifetime，把容器声明为static或readonly字段（单例复用） -
InitializeAsync()中启动容器，DisposeAsync()中停止并释放 - 不要在每个
[Fact]里重复启停——开销大，且StopAsync()可能被 GC 提前触发 - 若需每个测试独享数据库状态，就在
InitializeAsync()后执行CREATE DATABASE testdb;+ EF CoreMigrateAsync()，而非复用全局库
真正容易被忽略的是：容器启动完成 ≠ 应用服务就绪。SQL Server 启动后还需几秒初始化 master DB，务必配 WithWaitStrategy(Wait.ForUnixContainer().UntilMessageIsLogged("Service Broker manager has started")) 或自定义健康检查。
