mybatis-config.xml 是 MyBatis 框架的核心配置文件，它不是用来写 SQL 的，而是负责在框架启动时完成环境准备：告诉 MyBatis 连接哪台数据库、使用什么事务管理器、是否开启驼峰映射、去哪里加载 Mapper 映射文件。无论是原生 MyBatis 项目，还是用 Spring 整合 MyBatis，只要通过 SqlSessionFactoryBuilder 手动构建 SqlSessionFactory，都会优先读取这个文件。如果文件路径不对或内部元素顺序错误，通常会在启动阶段直接抛出异常，而不是等到执行 SQL 才暴露问题。
在 Java Web 项目中，这个文件一般放在类路径的根目录，例如 C:\Users\Administrator\IdeaProjects\demo\src\main\resources\mybatis-config.xml。该路径中的反斜杠在 Windows 系统中不能写成斜杠，否则资源加载器无法正确识别。接下来会从核心结构、数据源配置、映射器加载三个角度拆解配置方式。
mybatis-config.xml 的核心结构
整个配置文件的顶层元素只有一个 <configuration>，所有其他配置项都必须放在这个节点内部。MyBatis 对子元素的顺序有严格要求，如果顺序写错，在解析 XML 时就会抛出异常。官方推荐的顺序依次是：<properties>、<settings>、<typeAliases>、<typeHandlers>、<objectFactory>、<plugins>、<environments>、<databaseIdProvider>、<mappers>。实际项目中并不需要把所有节点都写全，但已经声明的节点必须遵循这个顺序。
其中 <properties> 用来引入外部属性文件，例如数据库账号密码单独放在 config.properties 中，避免硬编码到 XML 里。<settings> 控制框架的全局行为，比如开启驼峰命名转换可以让数据库字段 user_name 自动映射到 Java 属性 userName。<typeAliases> 用来给实体类配置短别名，减少 Mapper XML 中全限定类名的重复书写。<environments> 是环境配置的核心，可以定义多套环境并通过 default 属性指定当前生效的环境。
下面是一个结构完整的基础配置示例，包含了 properties、settings、typeAliases、environments 和 mappers 五个常用节点。
<?xml version="1.0" encoding="UTF-8" ?>
<configuration>
<properties resource="config.properties" />
<settings>
<setting name="mapUnderscoreToCamelCase" value="true" />
<setting name="logImpl" value="STDOUT_LOGGING" />
</settings>
<typeAliases>
<package name="com.example.entity" />
</typeAliases>
<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" />
<property name="username" value="root" />
<property name="password" value="123456" />
</dataSource>
</environment>
</environments>
<mappers>
<mapper resource="mapper/UserMapper.xml" />
</mappers>
</configuration>
这段配置虽然简短，但已经覆盖了 MyBatis 启动所需的全部关键信息。实际开发中，如果引入 Spring Boot 后不再单独使用 mybatis-config.xml，一些全局设置会迁移到 application.yml 中，但理解这个文件对排查配置问题仍然很有价值。
如何配置数据源与事务管理
数据源和事务管理是 mybatis-config.xml 中与数据库交互最密切的部分，全部位于 <environments> 节点下。一个 <environments> 可以包含多个 <environment>，分别对应开发环境、测试环境和生产环境。<environments default="development"> 中的 default 属性指定默认使用哪一套环境。每个 <environment> 必须有唯一的 id，并且要声明事务管理器和数据源两个子节点。
<transactionManager> 的 type 属性支持 JDBC 和 MANAGED 两种值。JDBC 表示由 MyBatis 自己控制事务，调用 commit 或 rollback 时直接操作数据库连接；MANAGED 表示事务交给容器管理，常见于 Spring 或应用服务器环境。数据源节点 <dataSource> 的 type 属性支持 POOLED、UNPOOLED 和 JNDI。POOLED 使用 MyBatis 内置的连接池，可以复用连接，减少频繁建立数据库连接的开销；UNPOOLED 每次请求都创建新连接，适合简单测试或并发极低的场景；JNDI 则从应用服务器中获取数据源，适合传统 Java EE 工程。
在 POOLED 模式下，连接池由 MyBatis 自行维护，不需要额外引入第三方连接池依赖。它通过 property 子节点接收 driver、url、username、password 四个基础参数。数据库驱动类的选择与 MySQL 版本有关，MySQL 8 及以上应使用 com.mysql.cj.jdbc.Driver，旧版本则使用 com.mysql.jdbc.Driver。如果驱动类写错，项目启动时虽然不一定会立刻报错，但第一次真正连接数据库时就会抛出 ClassNotFoundException，因此建议在配置阶段就确认驱动名称。
如何加载 Mapper 映射文件
<mappers> 节点负责告诉 MyBatis 去哪里寻找 SQL 映射文件或 Mapper 接口。这是配置文件中容易出错的地方，因为路径写错时不会影响框架启动，但调用对应方法时会提示找不到 Mapped Statement。加载 Mapper 有四种方式，分别是 resource、url、class 和 package。resource 是最常用的方式，它从类路径下加载 XML 映射文件，例如 mapper/UserMapper.xml 表示文件位于类路径的 mapper 目录下。
如果项目使用注解方式开发，可以不用 XML 映射文件，直接通过 class 属性指定 Mapper 接口的完全限定名，MyBatis 会从接口上的注解中读取 SQL。多个 Mapper 接口可以使用 package 子节点进行批量扫描，这样就不需要为每个接口单独写一条配置。例如 <package name="com.example.mapper" /> 会加载该包下所有接口，同时还会尝试加载与接口同名的 XML 文件，因此要求 XML 文件和接口位于同一目录结构下。
<mappers>
<mapper resource="mapper/UserMapper.xml" />
<mapper resource="mapper/OrderMapper.xml" />
<mapper class="com.example.mapper.AdminMapper" />
<package name="com.example.mapper" />
</mappers>
在 Java 代码中加载 mybatis-config.xml 时，通常使用 MyBatis 提供的 Resources 工具类。它会自动从类路径查找文件，因此参数不需要写绝对路径，只需要写相对于类路径根目录的资源名。加载完成后，通过 SqlSessionFactory 打开 SqlSession，再获取对应的 Mapper 代理对象即可执行数据库操作。
String resource = "mybatis-config.xml";
InputStream inputStream = Resources.getResourceAsStream(resource);
SqlSessionFactory sqlSessionFactory = new SqlSessionFactoryBuilder().build(inputStream);
try (SqlSession session = sqlSessionFactory.openSession()) {
UserMapper mapper = session.getMapper(UserMapper.class);
User user = mapper.selectById(1);
System.out.println(user.getName());
}
这段代码展示了原生 MyBatis 的标准使用流程。实际项目中如果整合了 Spring，SqlSessionFactory 通常交给 Spring 容器管理，但底层仍然会读取 mybatis-config.xml 中的部分配置，特别是 settings 和 typeAliases 等全局设置。因此即使项目已经接入 Spring Boot，理解这个配置文件的加载机制依然有助于排查配置不生效的问题。
常见配置错误与排查思路
第一个常见错误是子元素顺序写反。例如把 <settings> 放在 <properties> 前面，MyBatis 会提示 The content of element type configuration must match 之类的异常。解决方法是严格按照官方给出的顺序排列，不需要的节点可以省略，但不能随意调整已有节点的位置。第二个常见错误是 mapper resource 路径不正确。XML 映射文件如果放在了 resources 下的 mapper 目录中，配置里必须写 mapper/UserMapper.xml，而不是 /mapper/UserMapper.xml，多一个前导斜杠会导致资源找不到。
第三个问题与驼峰映射有关。默认情况下 MyBatis 不会把数据库字段 user_name 自动映射为 Java 属性 userName，如果 SQL 查询返回了 user_name 字段，而实体类只有 userName 属性，结果就会是 null。此时需要在 <settings> 中开启 mapUnderscoreToCamelCase，配置值为 true。第四个问题出现在数据库驱动上，很多旧项目升级 MySQL 8 后仍然使用 com.mysql.jdbc.Driver，会导致连接失败，需要改成 com.mysql.cj.jdbc.Driver，同时建议在 URL 后面加上 serverTimezone 参数，避免时区错误。
排查配置问题时，可以优先开启 MyBatis 的日志输出。在 <settings> 中设置 logImpl 为 STDOUT_LOGGING，框架会把加载的 mapper 数量、执行的 SQL 以及参数打印到控制台。这样既能确认 mybatis-config.xml 是否被正确加载，也能快速定位 SQL 映射缺失的问题。掌握这些排查方法之后，再配合良好的目录规范，mybatis-config.xml 的配置基本不会成为项目推进的阻碍。
MyBatis配置mybatis-config.xml数据库连接池修改时间：2026-09-19 11:13:51