需统一Testcontainers各模块版本，推荐用testcontainers-bom管理；Spring Boot 3.2+用户须注意junit-jupiter版本兼容性，避免NoClassDefFoundError。
Testcontainers 启动失败：java.lang.NoClassDefFoundError: org/testcontainers/utility/DockerImageName
这是常见于依赖版本混乱的典型错误——testcontainers 主模块和子模块（如 postgresql、junit-jupiter）版本不一致导致类加载失败。
- 统一用 BOM 管理依赖，Maven 中引入
testcontainers-bom，再声明各模块时不写版本号 - 避免混用
org.testcontainers:testcontainers1.17.x 和org.testcontainers:postgresql1.18.x —— 即使只差一个小版本，内部 API 也可能断裂 - Spring Boot 3.2+ 用户注意：
spring-boot-starter-test自带的junit-jupiter是 5.10+，而旧版 Testcontainers（@RegisterExtension 支持不稳定，建议升到1.19.0+
PostgreSQL 容器初始化 SQL 不执行：jdbc:tc:postgresql://... 没反应
Testcontainers 的 JDBC URL 方式（tc: 前缀）默认只拉镜像、启动容器，**不会自动执行 initScript 或 schema.sql** —— 这是很多人卡住的第一步。
- 改用
GenericContainer+withClasspathResourceMapping()手动挂载 SQL 文件，并通过withCommand()调用psql执行（适合复杂初始化） - 更轻量的做法：用
PostgreSQLContainer子类，调用.withInitScript("init.sql")—— 注意该方法只在容器首次启动时生效，且init.sql必须在 classpath 根路径下 - 别把
init.sql放进src/test/resources/db/就以为能被识别；路径必须是src/test/resources/init.sql，或显式传入Paths.get("src/test/resources/db/init.sql")并用withFileSystemBind()
CI 环境里 Docker daemon 不可用：GitHub Actions / GitLab CI 报 Cannot connect to the Docker daemon
本地跑通不代表 CI 能过。Testcontainers 默认尝试连接 unix:///var/run/docker.sock，但多数 CI 环境没暴露该 socket，或权限受限。
- GitHub Actions 必须加
services块启用docker:dind，并设DOCKER_HOST=tcp://localhost:2376和DOCKER_TLS_VERIFY=1 - GitLab CI 需配置
docker:dindservice，并在before_script中运行docker info确认连通性 —— 很多人漏掉这步，导致测试直接跳过容器启动，静默失败 - 如果实在无法启用 Docker，可降级为使用
H2DatabaseContainer或EmbeddedPostgres做单元测试，但要清楚：这不是“容器化测试”，只是绕过问题
测试执行慢、随机超时：容器拉取镜像阻塞在 Pulling from library/postgres
默认行为是每次测试都拉最新镜像，既慢又不可控。镜像拉取失败或网络抖动会直接让整个测试套件挂起。
立即学习“Java免费学习笔记（深入）”；
- 强制指定镜像标签，例如
new PostgreSQLContainer("postgres:15.4")，避免隐式拉latest - 在 CI 前置步骤预拉镜像：
docker pull postgres:15.4，然后 Testcontainers 会复用本地镜像 - 本地开发时，用
TESTCONTAINERS_REUSE=true环境变量复用已运行容器（需配合withReuse(true)），但注意：多个测试共用一个容器时，数据库状态会污染，仅适合单测串行场景
真正麻烦的是跨团队协作时，有人本地开了 Docker Desktop，有人用 Colima，有人关了 Linux cgroup v2 —— 这些底层差异会让容器启动行为不一致，却很难在日志里直接看到原因。
