testcontainers 在 go 中失败主因是 docker 未运行或权限不足；需正确配置 docker 环境、使用动态端口与就绪检查、随机化容器名和数据库名、手动调用 terminate 清理，并确保测试间数据隔离。
Testcontainers 在 Go 里跑不起来，大概率是没装 Docker 或权限不对
Go 的 testcontainers-go 不是纯库，它依赖宿主机的 Docker 守护进程。常见报错像 failed to dial docker socket 或 connection refused，基本就是 Docker 没运行、没加用户组、或 macOS 上 Docker Desktop 没启动。
- Linux 下确认用户在
docker组：sudo usermod -aG docker $USER，然后重新登录终端 - macOS / Windows：确保 Docker Desktop 已启动且状态栏图标是绿色
- CI 环境（如 GitHub Actions）需显式启用 Docker：用
docker/setup-qemu-action+docker/setup-buildx-action，再启动docker服务 - 别用 root 用户跑测试——
testcontainers-go默认走 Unix socket，root 启动的 Docker 和普通用户权限不互通
PostgreSQL 容器启动后连不上，检查端口映射和就绪探测
本地跑通不代表集成测试能连上。容器 IP 是动态的，localhost:5432 在容器内不等于宿主机的 localhost；而且 PostgreSQL 启动有延迟，刚创建完容器就 dial，大概率失败。
- 用
container.Host() + container.MappedPort()拿真实可连地址，别硬写localhost:5432 - 必须加就绪检查（
WaitForLogOutput或WaitForListeningPort），PostgreSQL 日志里出现database system is ready to accept connections才算真正就绪 - 镜像选
postgres:15-alpine这类轻量版，避免postgres:latest因基础镜像变更导致行为不一致 - 连接字符串里别漏
sslmode=disable——默认开启 SSL，但 testcontainer 启的 PG 实例不带证书
测试结束没清理容器，CI 跑几次就磁盘爆满
testcontainers-go 默认不会自动删容器，defer container.Terminate(ctx) 必须手动写，而且得放在 TestMain 或每个 TestXxx 函数末尾，不能只靠 defer 包裹在 setup 里。
- 最稳妥写法是在
TestMain中统一管理生命周期：os.Exit(m.Run())前调用所有容器的Terminate - 用
testcontainers.WithLogger开日志，能看到容器启停记录，方便排查残留 - CI 中建议加超时兜底：比如用
docker system prune -f --filter "until=30m"清理陈旧容器，避免因 panic 导致Terminate没执行 - 别依赖
defer container.Terminate(ctx)放在子函数里——如果测试 panic，defer 可能不触发
多个测试并行跑 PostgreSQL，端口冲突或数据污染
一个容器被多个测试共用，要么连不上（端口被占），要么前一个测试改了表结构，后一个测试直接挂掉。testcontainers-go 本身不解决并发隔离问题，得自己设计。
立即学习“go语言免费学习笔记（深入）”；
- 每个测试用独立容器：用
testcontainers.GenericContainer+ 随机容器名（比如加uuid.NewString()），别复用container实例 - 数据库名也随机化，通过
WithEnv("POSTGRES_DB=myapp_test_" + uuid.NewString())注入 - 避免在
TestMain里启一个全局 DB——看似省资源，实则让测试失去原子性，CI 失败难定位 - 如果真要共享（比如初始化耗时太久），至少用
sync.Mutex控制写操作，并在每个测试前TRUNCATE TABLE或重建 schema
容器生命周期和数据库状态隔离是两件事，光清容器不重置数据，照样串 test。别图省事跳过这步。
