非SpringBoot环境下Spring Data JPA的entityManagerFactory创建失败排查

阿华AIGC实验室

2026-5-14

解决方案：一步步排查并修复 entityManagerFactory 创建失败问题

从你遇到的org.springframework.beans.factory.BeanCreationException（无法创建entityManagerFactory）以及嵌套的JdbcEnvironment异常来看，这个问题在脱离Spring Boot手动搭建Spring Data JPA的场景里太常见了，核心大概率出在依赖兼容性、数据源配置、Hibernate核心配置这几个环节，下面是具体的排查和修复步骤：

1. 先把依赖版本的兼容性捋顺（最容易踩的坑）

脱离了Spring Boot的自动依赖管理，你得手动保证Spring Data JPA、Hibernate、Spring Context、JDBC驱动这些组件的版本完全匹配，版本不兼容会直接导致类加载失败或者服务初始化异常。

给你一个经过验证的兼容版本组合（以MySQL为例），你可以参考调整：

<!-- Spring 核心上下文 -->
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-context</artifactId>
    <version>6.0.11</version>
</dependency>
<!-- Spring Data JPA -->
<dependency>
    <groupId>org.springframework.data</groupId>
    <artifactId>spring-data-jpa</artifactId>
    <version>3.1.3</version>
</dependency>
<!-- Hibernate Core（Spring Data JPA 3.x必须对应Hibernate 6.x，别乱搭） -->
<dependency>
    <groupId>org.hibernate.orm</groupId>
    <artifactId>hibernate-core</artifactId>
    <version>6.2.7.Final</version>
</dependency>
<!-- MySQL JDBC驱动（对应MySQL 8.x，旧版本数据库换对应驱动） -->
<dependency>
    <groupId>com.mysql</groupId>
    <artifactId>mysql-connector-j</artifactId>
    <version>8.0.33</version>
</dependency>
<!-- Spring JDBC（数据源配置可能需要） -->
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-jdbc</artifactId>
    <version>6.0.11</version>
</dependency>

划重点：如果你非要用Hibernate 5.x，那Spring Data JPA必须用2.x系列，跨版本混用绝对出问题。

2. 检查数据源配置的细节

你的SpringDataConfig里的数据源Bean，一定要确保这几点没写错：

数据库URL：MySQL 8.x必须加serverTimezone参数，比如jdbc:mysql://localhost:3306/your_db?serverTimezone=UTC&useSSL=false，别漏了时区配置
驱动类名：MySQL 8.x是com.mysql.cj.jdbc.Driver，旧版本才是com.mysql.jdbc.Driver，别搞混
用户名/密码：别手抖打错，尤其是生产环境的复杂密码
数据源实现：推荐用HikariDataSource（性能更好），别用老旧的DriverManagerDataSource

示例正确的数据源配置：

@Bean
public DataSource dataSource() {
    HikariDataSource dataSource = new HikariDataSource();
    dataSource.setDriverClassName("com.mysql.cj.jdbc.Driver");
    dataSource.setJdbcUrl("jdbc:mysql://localhost:3306/test_db?serverTimezone=UTC&useSSL=false");
    dataSource.setUsername("root");
    dataSource.setPassword("your_db_password");
    return dataSource;
}

3. 补全EntityManagerFactory的核心JPA配置

创建entityManagerFactory时，Hibernate需要关键配置才能识别数据库环境和实体类，缺了这些就会报JdbcEnvironment异常：

@Bean
public LocalContainerEntityManagerFactoryBean entityManagerFactory(DataSource dataSource) {
    LocalContainerEntityManagerFactoryBean em = new LocalContainerEntityManagerFactoryBean();
    em.setDataSource(dataSource);
    // 必须指定实体类所在的包路径，不然Hibernate找不到实体
    em.setPackagesToScan("com.yourproject.entity");
    
    HibernateJpaVendorAdapter vendorAdapter = new HibernateJpaVendorAdapter();
    em.setJpaVendorAdapter(vendorAdapter);
    
    Properties properties = new Properties();
    // 数据库方言必须和你的数据库版本匹配，这是JdbcEnvironment初始化的关键
    properties.setProperty("hibernate.dialect", "org.hibernate.dialect.MySQL8Dialect");
    // 可选：自动建表策略，根据需求调整（create/update/validate等）
    properties.setProperty("hibernate.hbm2ddl.auto", "update");
    // 可选：显示SQL，方便调试
    properties.setProperty("hibernate.show_sql", "true");
    em.setJpaProperties(properties);
    
    return em;
}

重点提示：hibernate.dialect绝对不能省，不同数据库的方言不一样，比如PostgreSQL用PostgreSQLDialect，MySQL 5.x用MySQL5Dialect，省略这个参数Hibernate就无法正确识别JDBC环境，直接触发你遇到的异常。

4. 检查实体类的映射是否合法

如果实体类的注解有错误，也会间接导致entityManagerFactory创建失败，比如：

类上没加@Entity注解
主键字段没加@Id，或者生成策略配置错误（比如用了IDENTITY但数据库主键不是自增）
字段映射和数据库类型不匹配（比如把日期字段映射成字符串）

一定要确保每个实体类的基础注解都正确，比如：

@Entity
@Table(name = "user")
public class User {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    
    @Column(name = "username", length = 50, nullable = false)
    private String username;
    
    // 其他字段、getter/setter
}