本文详解如何解决 Spring Boot 集成 Testcontainers 与 Liquibase 时，因测试容器 URL 配置不当导致 Liquibase 在每次测试启动时重复执行初始化数据（如 insert_test_user.yaml），进而触发 PostgreSQL 唯一索引（如 user_email_key）冲突的问题。
本文详解如何解决 spring boot 集成 testcontainers 与 liquibase 时，因测试容器 url 配置不当导致 liquibase 在每次测试启动时重复执行初始化数据（如 insert_test_user.yaml），进而触发 postgresql 唯一索引（如 `user_email_key`）冲突的问题。
在基于 Testcontainers + Liquibase 的 Spring Boot 集成测试中，一个常见但隐蔽的问题是：Liquibase 迁移脚本（尤其是用于预置测试数据的 INSERT 类 changeset）被重复执行，最终因违反数据库唯一约束（如 user_email_key）而抛出 MigrationFailedException，导致整个测试上下文加载失败。
根本原因在于：Testcontainers 实例未被 Liquibase 正确识别为“一次性、隔离的测试数据库”。当 application-test.properties 中仍使用静态 JDBC URL（如 jdbc:postgresql://localhost:5432/postgres）和原生 PostgreSQL 驱动时，Spring Boot 会绕过 Testcontainers 的生命周期管理——Liquibase 在应用启动时直接连接到宿主机上的 PostgreSQL 实例（甚至可能是残留的旧容器），而非当前测试专属的、空且全新的容器数据库。更严重的是，若该数据库已存在并已被 Liquibase 执行过 insert_test_user.yaml，再次运行测试就会因重复插入相同邮箱而失败。
✅ 正确解法是显式启用 Testcontainers 的 JDBC 代理驱动，确保 Liquibase 始终操作的是由 @Container 注解声明的、生命周期受控的 PostgreSQL 容器：
# application-test.properties spring.datasource.driver-class-name=org.testcontainers.jdbc.ContainerDatabaseDriver spring.datasource.url=jdbc:tc:postgresql://localhost:5432/test
⚠️ 注意事项：
jdbc:tc:postgresql://...是 Testcontainers 提供的特殊 JDBC 协议，它会在首次连接时自动拉起并配置 PostgreSQL 容器，并将连接路由至该容器；- 数据库名（如
/test）可自定义，但必须与容器内实际创建的数据库名一致（PostgreSQLContainer 默认为test）；- 务必移除或注释掉原有静态配置（如
spring.datasource.url=jdbc:postgresql://...），否则将造成配置冲突；- 若使用 Liquibase 的
changeLog路径包含includeAll，请确保db/changelog/inserts/下的 YAML/SQL 文件具有幂等性（例如使用<pre class="brush:php;toolbar:false;"Conditions></code> 检查记录是否存在），或仅在 <code>@Sql</code> 或 <code>@BeforeEach</code> 中按需插入测试数据，避免依赖 Liquibase 自动执行初始数据。</li></ul></blockquote><p>此外，建议在 <code>BaseIntegrationTest</code> 中显式重置数据库状态以增强可靠性（非必需但推荐）：</p><pre class="brush:php;toolbar:false;">@BeforeEach void resetDatabase() { // 清空所有表（适用于测试专用 schema） userRepository.truncateAll() }</pre><p>或通过 Liquibase 的 <code>dropAll命令配合spring.liquibase.drop-first=true（仅限开发/测试环境）实现更彻底的隔离。总结：该问题本质是测试基础设施层的连接路由错位，而非 Liquibase 或业务逻辑缺陷。只需将数据源配置切换至 Testcontainers JDBC 代理协议，即可让 Liquibase 真正作用于“干净、独占、按需创建”的容器数据库，从根本上杜绝重复迁移与约束冲突。
