goland 连不上 docker 是 testcontainers 启动失败的主因，90% 源于未正确配置 docker 连接：需在 settings → tools → docker 中指定正确路径并补全 docker_host 环境变量；testmain 中必须显式管理容器生命周期；数据库连接字符串须动态获取映射端口，不可硬编码 localhost:5432。
GoLand 连不上 Docker 是最常见失败原因
Testcontainers 启动失败，90% 不是 Go 代码问题，而是 GoLand 根本没连上 Docker 守护进程。终端里 docker ps 能跑通 ≠ GoLand 能调用 Docker —— 它默认不继承 shell 环境变量，也不自动读取 ~/.docker/config.json。
必须手动确认三件事：
- Settings → Tools → Docker 中已勾选 “Docker executable”，路径正确（macOS 通常是
/usr/local/bin/docker，Linux 常为/usr/bin/docker） - Windows 用户需确认 WSL2 已启用，且 Docker Desktop 的上下文设为
wsl（不是default） - macOS 上 Docker Desktop 图标必须是实心蓝色，未启动或权限不足时 socket 会被拒绝访问
如果仍报 Cannot connect to the Docker daemon，在 Run Configuration → Environment variables 里显式补全：DOCKER_HOST=unix:///var/run/docker.sock（macOS/Linux）或 DOCKER_HOST=tcp://localhost:2375（Windows + Docker Desktop 开启 TCP 暴露）
TestMain 中容器生命周期管理不能省略
反复点「Run Test」后容器不销毁，端口被占、数据库残留数据，下一次测试直接挂——这不是 bug，是你没写 container.Terminate(ctx)。
TestMain 是唯一可靠的位置：所有测试前拉起，所有测试后统一销毁。别把 Terminate 放进单个 TestXXX 函数里，GoLand 并行跑测试时会触发竞态销毁。
关键动作：
GoLand 2026.1.1 是 2026.1 发布后的首个维护修正版本，适合已经开始体验 2026.1 新功能并希望同步补丁的开发者。它更适合用于入门项目、现有项目迁移测试和 IDE 行为验证。
- 把容器句柄存成包级变量（如
var pgContainer testcontainers.Container） - 在
TestMain开头启动，在defer m.Run()之后调用pgContainer.Terminate(ctx) - 加
ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)防止容器卡死拖垮整个测试套件 - 销毁失败不能静默吞掉错误，用
t.Log("failed to terminate container:", err)记录，否则下次测试连不上端口都不知道为什么
连接字符串必须动态获取，硬编码 localhost:5432 必挂
你在 GoLand 里看到 dial tcp 127.0.0.1:5432: connect: connection refused，大概率是因为测试代码还在连 localhost:5432，而 Testcontainers 启的 PostgreSQL 容器映射的是随机端口（比如 54321）。
必须从容器实例动态提取地址：
- 用
container.Host()获取宿主机 IP（注意：不是localhost，CI 或 WSL2 下localhost可能不通） - 用
container.MappedPort(t, "5432/tcp")获取实际映射端口 - 拼成
host:port后构造 DSN，例如：fmt.Sprintf("host=%s port=%s user=test password=test dbname=test sslmode=disable", container.Host(), container.MappedPort(t, "5432/tcp")) - 千万别在
init()或包级变量里硬编码连接字符串；改用函数参数或结构体注入，方便测试替换
CI 环境里没装 Docker 或没开 dockerd 就白搭
本地能跑 ≠ CI 能跑。很多团队卡在这一步：CI 流水线用的是干净容器镜像，里面压根没装 Docker，或者没启动 dockerd 服务。
检查点很实在：
- CI 脚本开头加
docker --version和docker ps，确认 Docker CLI 和守护进程都就位 - GitHub Actions 需显式启用
services，GitLab CI 需配置docker:dindservice 并挂载/var/run/docker.sock - 若用自建 runner，确保其运行用户有
docker组权限，且dockerd已 systemctl enable 启动 - Testcontainers 默认超时是 60 秒，CI 网络慢或镜像拉取慢时容易失败，建议在启动容器时传
testcontainers.WithWaitStrategy(wait.ForListeningPort("5432/tcp").WithStartupTimeout(120 * time.Second))
最容易被忽略的是：Testcontainers 启动失败时不会中断测试流程，而是让后续 DB 连接逻辑静默失败。务必在 TestMain 初始化阶段做一次 sql.Open + db.PingContext 验证，失败就 os.Exit(1)，别等测试跑一半才暴露环境问题。
