根本原因是 docker daemon 不可用、权限不足或默认超时太短；需验证 docker info、使用健康检查容器、显式设超时、动态获取映射端口、等待服务就绪日志、启用全局回收器并正确拼接连接地址。
testcontainers-go 启动容器总卡住或超时
根本原因通常是 Docker daemon 不可用、权限不足，或默认超时太短。本地开发时容易忽略 dockerd 是否真正运行（比如 macOS 上 Docker Desktop 未启动，或 Linux 上用户没加 docker 组），导致 testcontainers-go 在 Connect() 阶段阻塞。
- 先手动执行
docker info确认连通性，失败就别跑测试了 - 在
TestMain或测试前加健康检查：req := testcontainers.ContainerRequest{Image: "hello-world", AutoRemove: true}，用它快速验证环境 - 显式设置超时：传入
testcontainers.WithLogger(log.New(os.Stderr, "", 0))和testcontainers.WithTimeout(60 * time.Second)，避免默认 60 秒不够用（尤其 CI 中拉镜像慢） - Windows WSL2 用户注意：Docker Desktop 默认不共享
/tmp，testcontainers-go的 socket 挂载可能失败，改用DOCKER_HOST=tcp://host.docker.internal:2375
怎么让容器暴露端口并等服务真正就绪
testcontainers-go 的 WithExposedPorts 只是声明端口，不等于能立刻连上；真实服务（如 PostgreSQL、Redis）需要时间初始化，直接 net.Dial 极大概率失败。
- 必须用
WaitForLogOutput或WaitForListeningPort：比如 PostgreSQL 日志出现"database system is ready to accept connections"才算活了 - 别依赖固定端口映射：用
container.MappedPort(ctx, "5432/tcp")动态取 host 端口，再拼接host:port连接字符串 - 对 HTTP 服务，优先用
WaitForHTTP（支持自定义路径和状态码），比轮询http.Get更稳 - 注意：PostgreSQL 容器默认监听
localhost，需改POSTGRES_HOST_AUTH_METHOD=trust并挂载pg_hba.conf或用127.0.0.1/0授权，否则 Go 测试进程连不上
测试完容器没清理，CI 跑几次就磁盘爆了
testcontainers-go 默认不会自动清理失败的容器，defer container.Terminate(ctx) 在 panic 或 context cancel 时可能不执行，尤其测试用例多、超时频繁的场景下，残留容器越积越多。
- 必须用
testcontainers.NewReaper启一个全局回收器，哪怕测试 panic 也能兜底清理 - 在
TestMain中统一管理生命周期：reaper, _ := testcontainers.NewReaper(ctx, "test-namespace")，然后defer reaper.Cleanup() - 避免在每个测试里单独
Terminate：容易漏写，也干扰并行测试（多个测试共用一个容器时更危险） - CI 环境建议加
docker system prune -f到 job 结尾，防万一——reaper不能覆盖所有异常退出路径
Go 测试中连接数据库却报 “connection refused” 或 “dial tcp: i/o timeout”
不是网络问题，而是 Go 测试代码和容器之间存在「时间差」和「地址错配」。常见于没等容器就绪就 dial，或用了错误的 host 名。
- Docker 内部网络中，容器间用容器名通信（如
postgres），但 Go 测试进程在宿主机运行，必须用host.docker.internal（macOS/Windows）或172.17.0.1（Linux）作为 host - 别硬编码
localhost:5432：本地开发可能碰巧通，但 CI 中容器网络隔离后必挂 - 用
container.Host(ctx)+container.MappedPort(ctx, "5432/tcp")拼地址最可靠 - PostgreSQL 示例连接字符串：
host=host.docker.internal port=5432 user=test password=test dbname=test sslmode=disable（注意sslmode=disable，除非你真启了 SSL）
最麻烦的是日志看不到容器启动失败细节——记得加 testcontainers.WithLogger，不然只能去 docker logs <cid></cid> 手动翻。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
