Testcontainers for .NET 在 CI 中可稳定运行，前提是宿主机已安装并配置好 Docker Engine；需通过 docker info 验证 daemon 可达，使用 GetConnectionString() 获取动态端口，避免硬编码 localhost:5432，并合理配置等待策略与镜像以应对启动超时。
Testcontainers for .NET 能否在 CI 环境中稳定运行
能，但前提是宿主机（或 CI agent）已安装 Docker Engine 且 docker 命令可被进程访问。Testcontainers for .NET 不是模拟器，它真实调用 Docker API 启动容器——这意味着它依赖本地或远程 Docker daemon。GitHub Actions、Azure Pipelines、GitLab CI 都支持，只要 runner 配置了 dockerd 或使用 docker-in-docker（dind）服务。
常见失败场景：
- Docker daemon 未启动或权限不足（Linux 上常因用户不在
docker组） - CI runner 使用无 Docker 的轻量镜像（如
ubuntu-latest默认不含docker，需显式安装） - Windows 上启用 WSL2 后未配置好跨子系统访问（.NET 进程在 Windows，Docker 在 WSL2，默认 socket 路径不通）
验证方式：在测试项目根目录运行 docker info，能输出 Server 部分即表示可达。
如何编写一个 PostgreSQL 容器的单元测试
以 xUnit 为例，核心是继承 IAsyncLifetime，在 InitializeAsync 中启动容器，在 DisposeAsync 中清理。Testcontainers 提供强类型容器构建器，比如 PostgreSqlContainer 会自动处理端口映射、健康检查、连接字符串生成。
关键实操点：
- 使用
WithDatabase("testdb")和WithUsername("testuser")显式设置凭据，避免依赖默认值 - 务必调用
WithWaitStrategy(Wait.ForUnixContainer().UntilMessageIsLogged("database system is ready to accept connections"))，PostgreSQL 启动慢，仅靠端口就绪不够 - 连接字符串从
container.GetConnectionString()获取，它已包含正确 host（host.docker.internal在 Linux/macOS 需手动映射，.NET SDK 8+ 的 Testcontainers 默认启用WithHostNameAsContainerName()）
示例片段：
public class PostgreSqlTests : IAsyncLifetime
{
private readonly PostgreSqlContainer _container = new PostgreSqlBuilder()
.WithDatabase("testdb")
.WithUsername("testuser")
.WithPassword("testpass")
.WithWaitStrategy(Wait.ForUnixContainer()
.UntilMessageIsLogged("database system is ready to accept connections"))
.Build();
public async Task InitializeAsync() => await _container.StartAsync();
public async Task DisposeAsync() => await _container.StopAsync();
[Fact]
public async Task Can_Query_With_Dapper()
{
using var conn = new NpgsqlConnection(_container.GetConnectionString());
await conn.OpenAsync();
var count = await conn.QuerySingleAsync<int>("SELECT 1");
Assert.Equal(1, count);
}
}
为什么 Testcontainers 启动容器后连接不上 localhost:5432
因为容器内进程看到的 localhost 是它自己的回环地址，不是宿主机。.NET 测试进程运行在宿主机（或 CI runner），而容器在 Docker 网络中，两者网络隔离。
正确做法是：
- 永远用
_container.GetConnectionString()，它返回形如Host=localhost;Port=32768;Database=testdb;...的字符串，其中Port是 Docker 映射到宿主机的随机端口（非固定 5432） - 不要硬编码
localhost:5432—— 即便你用WithPortBinding(5432)，也应通过_container.GetMappedPublicPort(5432)动态获取实际绑定端口 - 若需容器间通信（比如测试服务 A 调用容器 B），则必须将测试进程也放进同一 Docker 网络（用
WithNetwork(...)），此时 host 应设为容器名而非localhost
错误典型：new NpgsqlConnection("Host=localhost;Port=5432;...") → 报错 Npgsql.NpgsqlException : Exception while connecting，本质是连到了宿主机本机的 PostgreSQL（如果装了），而非容器。
容器启动超时或反复重启怎么办
默认超时是 60 秒，对某些镜像（如 SQL Server、Elasticsearch）不够。根本原因通常是健康检查逻辑不匹配或资源不足。
应对策略：
- 调大超时：
WithWaitStrategy(Wait.ForUnixContainer().UntilMessageIsLogged("...").WithStartupTimeoutMs(120_000)) - 换更轻量的镜像：PostgreSQL 推荐用
postgres:15-alpine而非postgres:15；SQL Server 用mcr.microsoft.com/mssql/server:2022-latest-ubuntu-20.04（比 Windows 版快得多） - 禁用不必要的服务：例如 Elasticsearch 默认启用了 Kibana，加
WithEnvironment("discovery.type=single-node")可跳过集群发现耗时 - 检查日志：
await _container.GetLogsAsync()输出到 console，确认是否卡在初始化步骤（如 PostgreSQL 的 WAL recovery）
一个容易被忽略的点：Testcontainers 默认使用桥接网络，若宿主机防火墙拦截了随机映射端口（尤其 Windows Defender 防火墙），容器虽启动成功，但端口不可达——此时日志里看不到错误，但连接始终 timeout。
