testcontainers 在 go 中需使用 testcontainers-go；常见错误是未启动 docker 或权限不足，postgresql 测试须设 exposedports 和 waitingfor，容器应通过 testmain 全局管理并设 started: true。
Testcontainers 在 Go 里跑不起来？先确认你用的是 testcontainers-go
Go 生态没有官方 Testcontainers 实现，社区主流方案是 testcontainers-go。直接 go get github.com/testcontainers/testcontainers-go 就行，别误装 Java 版或 Python 版的客户端——那根本连不上本地 Docker daemon。
常见错误现象：failed to dial docker endpoint 或 context deadline exceeded，大概率是没装 Docker、Docker Desktop 没启动，或者 Linux 上没加当前用户到 docker 用户组。
- 必须确保
docker ps在终端能正常执行（非 root 用户需sudo usermod -aG docker $USER） - Mac / Windows 用户注意：Docker Desktop 必须运行中，且启用 “Start Docker Desktop when you log in”
- CI 场景（如 GitHub Actions）要显式启动
dockerd服务，不能只靠setup-docker-action
写一个 PostgreSQL 容器测试，ContainerRequest 的关键字段怎么填？
不是所有字段都得写全，但漏掉几个就会卡住：比如不设 WaitingFor，容器可能刚拉镜像就返回，Exec` 或 `sqlx.Open 直接 panic；不设 ExposedPorts，Go 代码连不上 localhost:5432。
典型最小可用配置：
立即学习“go语言免费学习笔记（深入）”；
req := testcontainers.ContainerRequest{
Image: "postgres:15",
ExposedPorts: []string{"5432/tcp"},
Env: map[string]string{
"POSTGRES_PASSWORD": "testpass",
"POSTGRES_DB": "testdb",
},
WaitingFor: wait.ForListeningPort("5432/tcp").
WithStartupTimeout(60 * time.Second).
WithPollInterval(2 * time.Second),
}-
ExposedPorts是必须项，即使只在容器内通信也要声明，否则端口映射不生效 -
WaitingFor推荐用ForListeningPort而非ForLog，PostgreSQL 启动日志不稳定，容易误判 - 别信镜像默认端口——
postgres:15默认是 5432，但timescale/timescaledb可能是 5432+8080，得查文档
测试完容器没清理？TerminationWaitTime 和 Stop 顺序很重要
Go 测试函数退出时容器还在跑，下次测试可能因端口占用失败，或 CI 环境残留大量僵尸容器。根本原因不是忘了 defer container.Terminate()，而是 Terminate() 默认等 10 秒才强制 kill，而 Stop() 不等就返回——如果你先 Stop 再 Terminate，后者实际什么也没做。
- 始终用
defer container.Terminate()，别自己调Stop() - 需要更快终止？构造
ContainerRequest时设TerminationWaitTime: 5 * time.Second - 调试阶段加
Logger: testcontainers.Logger{Writer: os.Stderr}，能看到容器启停的真实时间点
和 go test 集成时，-count=2 会重复创建容器？
Go 的 -count 参数会多次执行同一个测试函数，但 testcontainers-go 默认不共享容器实例。每次调 testcontainers.GenericContainer 都新建一个容器，端口冲突、资源耗尽、数据库状态污染全来了。
解决办法只有一个：把容器实例提到包级变量 + sync.Once 初始化，且仅在 TestMain 中启动/关闭：
var once sync.Once
var pgC *testcontainers.DockerContainer
<p>func TestMain(m *testing.M) {
once.Do(func() {
req := testcontainers.ContainerRequest{...}
pgC, _ = testcontainers.GenericContainer(context.Background(), testcontainers.GenericContainerRequest{
ContainerRequest: req,
Started: true,
})
})
code := m.Run()
if pgC != nil {
pgC.Terminate(context.Background())
}
os.Exit(code)
}- 别在单个
TestXxx函数里初始化容器——-count=2或go test ./... -race下必崩 -
Started: true必须设，否则GenericContainer返回后容器还没真正跑起来 - 如果测试之间需要隔离 DB 状态，就在每个 test 里用
pgx执行DROP SCHEMA public CASCADE; CREATE SCHEMA public;，而不是反复启停容器
容器生命周期和 Go 测试生命周期对不齐，是集成里最常被跳过的细节。一旦涉及并发测试、重试或模块化测试套件，这里出问题的概率远高于语法错误。
