MyBatis配置错误：驱动类未找到解决方案

问题描述

在使用MyBatis时遇到以下异常：

org.apache.ibatis.exceptions.PersistenceException: 
### Error querying database.  
Cause: java.sql.SQLException: Error setting driver on UnpooledDataSource. 
Cause: java.lang.ClassNotFoundException: Cannot find class: ${jdbc.driver}

问题分析

该错误表明MyBatis配置文件中的属性占位符 ${jdbc.driver} 没有被正确替换为实际的数据库驱动类名。主要原因包括：

1. 属性文件未正确加载
2. 属性文件路径错误
3. 属性文件内容格式不正确
4. Maven资源过滤未配置

解决方案

方案一：检查属性文件配置（最常见）

1. 确保 mybatis-config.xml 正确引入属性文件

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE configuration PUBLIC "-//mybatis.org//DTD Config 3.0//EN"
        "http://mybatis.org/dtd/mybatis-3-config.dtd">
<configuration>
    <!-- 关键：正确引入属性文件 -->
    <properties resource="db.properties"/>
    
    <environments default="development">
        <environment id="development">
            <transactionManager type="JDBC"/>
            <dataSource type="POOLED">
                <!-- 这些占位符会被db.properties中的值替换 -->
                <property name="driver" value="${jdbc.driver}"/>
                <property name="url" value="${jdbc.url}"/>
                <property name="username" value="${jdbc.username}"/>
                <property name="password" value="${jdbc.password}"/>
            </dataSource>
        </environment>
    </environments>
</configuration>

2. 检查 db.properties 文件内容

确保文件内容正确，根据MySQL版本选择合适的驱动：

MySQL 8.x：

这里面一定要加jdbc. 不然会显示错误
jdbc.driver=com.mysql.cj.jdbc.Driver
jdbc.url=jdbc:mysql://localhost:3306/your_database?useSSL=false&serverTimezone=UTC&characterEncoding=utf8
jdbc.username=root
jdbc.password=your_password

MySQL 5.x：

jdbc.driver=com.mysql.jdbc.Driver
jdbc.url=jdbc:mysql://localhost:3306/your_database?useUnicode=true&characterEncoding=utf8
jdbc.username=root
jdbc.password=your_password

方案二：检查文件路径和位置

确保项目结构正确：

项目目录/
├── src/
│   └── main/
│       ├── java/
│       │   └── com/.../
│       └── resources/                    # 属性文件应该在这里
│           ├── db.properties
│           └── mybatis-config.xml
├── target/
└── pom.xml

方案三：使用内联配置进行调试

临时在配置文件中直接写入数据库连接信息，以排除属性文件问题：

<configuration>
    <!-- 暂时注释掉属性文件引用 -->
    <!-- <properties resource="db.properties"/> -->
    
    <environments default="development">
        <environment id="development">
            <transactionManager type="JDBC"/>
            <dataSource type="POOLED">
                <!-- 直接硬编码数据库连接信息 -->
                <property name="driver" value="com.mysql.cj.jdbc.Driver"/>
                <property name="url" value="jdbc:mysql://localhost:3306/test_db"/>
                <property name="username" value="root"/>
                <property name="password" value="123456"/>
            </dataSource>
        </environment>
    </environments>
</configuration>

方案四：Maven资源过滤配置

如果使用Maven，确保 pom.xml 中配置了资源过滤：

<build>
    <resources>
        <resource>
            <directory>src/main/resources</directory>
            <filtering>true</filtering>  <!-- 关键：启用过滤 -->
            <includes>
                <include>**/*.properties</include>
                <include>**/*.xml</include>
            </includes>
        </resource>
    </resources>
</build>

配置后执行清理和重新构建：

mvn clean compile

方案五：验证和调试工具

1. 创建配置测试类

public class MyBatisConfigTest {
    public static void main(String[] args) {
        try {
            String resource = "mybatis-config.xml";
            InputStream inputStream = Resources.getResourceAsStream(resource);
            SqlSessionFactory factory = new SqlSessionFactoryBuilder().build(inputStream);
            System.out.println("✅ MyBatis配置加载成功！");
        } catch (Exception e) {
            System.err.println("❌ 配置加载失败：");
            e.printStackTrace();
        }
    }
}

2. 创建属性文件测试类

public class PropertiesFileTest {
    public static void main(String[] args) {
        try (InputStream input = PropertiesFileTest.class.getClassLoader()
                .getResourceAsStream("db.properties")) {
            
            if (input == null) {
                System.err.println("❌ 找不到db.properties文件");
                return;
            }
            
            Properties prop = new Properties();
            prop.load(input);
            
            System.out.println("=== db.properties 内容 ===");
            System.out.println("jdbc.driver: " + prop.getProperty("jdbc.driver"));
            System.out.println("jdbc.url: " + prop.getProperty("jdbc.url"));
            System.out.println("jdbc.username: " + prop.getProperty("jdbc.username"));
            
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

常见问题排查表

问题现象	可能原因	解决方案
报错显示 ${jdbc.driver} 原样	属性文件未加载	检查resource="db.properties"路径
报错显示类未找到，但类名正确	驱动jar包缺失	添加MySQL驱动依赖
属性值包含特殊字符	属性文件语法错误	检查是否需要转义字符
在IDE中正常，打包后出错	Maven资源过滤未配置	在pom.xml中添加<filtering>true</filtering>
文件修改后问题依旧	IDE或Maven缓存	执行mvn clean compile

快速修复步骤

1. 检查文件位置：确认 db.properties 在 src/main/resources 目录下
2. 检查文件内容：确认驱动类名正确（注意MySQL版本差异）
3. 清理项目：执行 mvn clean compile 或清理IDE缓存
4. 验证配置：运行测试类验证配置是否正确加载
5. 检查依赖：确保 pom.xml 中有MySQL驱动依赖

MySQL驱动依赖配置

确保Maven依赖中包含正确的MySQL驱动：

<dependency>
    <groupId>mysql</groupId>
    <artifactId>mysql-connector-java</artifactId>
    <version>8.0.33</version>  <!-- 根据你的MySQL版本选择 -->
</dependency>

预防措施

1. 统一配置管理：将数据库配置统一放在属性文件中
2. 版本一致性：确保MySQL驱动版本与数据库服务器版本匹配
3. 资源过滤：在Maven项目中始终配置资源过滤
4. 配置验证：在项目启动时添加配置验证逻辑
5. 文档化：在团队中共享数据库配置规范

通过以上步骤，应该能够解决MyBatis因属性占位符未替换导致的驱动类找不到的问题。建议从方案一开始逐一排查，多数情况下问题出在属性文件路径或内容上。