testcontainers-go 连不上 postgresql 主因是端口未映射、监听地址非 0.0.0.0、就绪检查未生效；须动态获取 host 和 mapped port，加 sslmode=disable，并用 forlisteningport 等待。

testcontainers-go 跑不起来，90% 是 Docker 没连上；连上了但连不上 PostgreSQL，基本是端口、监听地址、就绪时机三处没对齐。

docker info 都过不了，别急着写测试

testcontainers-go 不是纯 Go 库，它必须能调用宿主机的 Docker daemon。常见失败现象：failed to dial docker socket、connection refused、context deadline exceeded。这些不是代码问题，是环境没通。

• 先手动跑 docker info：成功返回才继续；失败就检查 Docker Desktop 是否启动（macOS/Windows），或 Linux 用户是否在 docker 组里（sudo usermod -aG docker $USER）
• WSL2 用户注意：/tmp 默认不共享，socket 挂载会失败；改用 DOCKER_HOST=tcp://host.docker.internal:2375
• CI 环境（如 GitHub Actions）必须显式启用 Docker：用 docker/setup-qemu-action + docker/setup-buildx-action，再确保 services 或 dockerd 启动成功

PostgreSQL 容器启动了，但 net.Dial 直接报 connection refused

容器进程在跑 ≠ 你能连上。根本原因有三个：PostgreSQL 监听地址不对、端口没真正映射、服务还没初始化完。

Alibabacloud Sdk Client Initialization For Golang

初始化并管理阿里云SDK Go 客户端，涵盖 sync.Once 单例、goroutine 安全、endpoint 与 region 配置、VPC 端点及调试。

下载

• PostgreSQL 默认只监听 127.0.0.1，而 testcontainers 的容器网络靠桥接，宿主机必须通过 0.0.0.0 访问——加环境变量 POSTGRES_HOST_AUTH_METHOD=trust 并确保镜像支持监听全地址（官方镜像默认已支持）
• ExposedPorts: []string{"5432/tcp"} 只是声明，不等于端口已映射；硬写 localhost:5432 必败；必须用 container.Host(ctx) + container.MappedPort(ctx, "5432/tcp") 动态拼地址
• 连接字符串里漏 sslmode=disable 会导致默认走 SSL 握手失败；testcontainers 启的 PG 实例不带证书，必须显式关掉

就绪检查不能省，ForListeningPort 比 ForLogOutput 更可靠

刚 container.Start() 返回，不代表 PostgreSQL 已 ready。日志输出时机不稳定，不同镜像格式还可能变；而端口监听状态更底层、更确定。

• 用 wait.ForListeningPort("5432/tcp")，不是 wait.ForLogOutput("database system is ready")
• 必须设超时：WithStartupTimeout(60 * time.Second)（CI 拉镜像慢，60 秒是底线）
• 加轮询间隔：WithPollInterval(2 * time.Second)，避免高频探测压垮 Docker daemon
• 完整写法示例：

  WaitingFor: wait.ForListeningPort("5432/tcp").
      WithStartupTimeout(60 * time.Second).
      WithPollInterval(2 * time.Second),

TestMain 里不启全局回收器，CI 跑几次磁盘就满了

单个测试里写 defer container.Terminate(ctx) 看似简单，但 panic、context cancel、超时都会让它不执行。残留容器越积越多，CI 磁盘爆满是常态。

• 必须在 TestMain 中启全局回收器：reaper, _ := testcontainers.NewReaper(ctx, "test-namespace")，然后 defer reaper.Cleanup()
• 不要依赖 defer 清理单个容器；reaper.Cleanup() 能兜底所有未终止容器，哪怕测试 panic 也能回收
• 如果多个测试共用一个数据库容器，Terminate 放在 TestMain 结尾统一处理，而不是每个 TestXxx 里重复写
• CI 中可额外加兜底命令：docker system prune -f --filter "until=30m"，防回收器失效

最易被忽略的一点：PostgreSQL 容器名、数据库名、用户密码都该随机化。硬编码 postgres/postgres 在并行测试中会冲突，尤其当多个测试套件同时跑时，数据隔离就破了。

golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！