HibernatePersistenceProvider配置报错：无法兼容JPA持久化接口

在persistence.xml中配置以下代码时出现类型不匹配错误：

<provider>org.hibernate.jpa.HibernatePersistenceProvider</provider>

错误提示：

'org.hibernate.jpa.HibernatePersistenceProvider' is not assignable to 'javax.persistence.spi.PersistenceProvider,jakarta.persistence.spi.PersistenceProvider'

问题根源 #

这个错误核心是Hibernate版本与JPA API规范不兼容，或者项目中同时引入了javax.persistence（Java EE时代JPA）和jakarta.persistence（Jakarta EE时代JPA）两套API依赖，导致类加载时类型无法匹配。

具体解决步骤 #

• 对齐Hibernate版本与JPA API
  • 若使用Hibernate 5.x：它依赖javax.persistence规范，确保项目只引入javax.persistence-api依赖，不要混入jakarta.persistence-api。此时配置的org.hibernate.jpa.HibernatePersistenceProvider是正确的，冲突多来自依赖重复引入。
  • 若使用Hibernate 6.x：它已全面适配Jakarta EE，依赖jakarta.persistence-api，同样可以使用org.hibernate.jpa.HibernatePersistenceProvider，但要彻底清理项目中javax.persistence相关依赖。
• 排查并清理依赖冲突
  • 用构建工具的依赖分析命令找出冲突：
    • Maven：执行 mvn dependency:tree，检查输出中是否同时存在javax.persistence和jakarta.persistence相关依赖，删除多余的一套。
    • Gradle：执行 gradle dependencies，同理排查并移除冲突依赖。
• 校验类路径
  • 确保项目编译、运行时的类路径中，只有一套JPA API（要么全是javax，要么全是jakarta），且与Hibernate版本完全对应。

内容的提问来源于stack exchange，提问作者temez