java mybatis为何启动报错

MyBatis 在 Java 项目启动时报错，原因非常多，常见的主要集中在 配置、依赖、XML、Mapper 扫描 这几类。下面我按「最常见 → 较少见」给你一个排查清单，你可以对照看看。

一、最常见原因（80% 都在这里）

1️⃣ Mapper.xml 路径/命名不对

典型报错：

Invalid bound statement (not found)

✅ 检查点：

• namespace 是否等于 Mapper 接口全路径

<mapper namespace="com.xxx.mapper.UserMapper">

• id 是否和接口方法名一致

<select id="selectById" ...>

• XML 是否在 resources 对应目录中（包结构一致）

2️⃣ Mapper 接口没有被扫描

典型报错：

No qualifying bean of type 'xxxMapper' available

✅ 检查：

• Spring Boot：

@MapperScan("com.xxx.mapper")

或 Mapper 接口上加：

@Mapper

• 多模块项目尤其容易漏

3️⃣ MyBatis 依赖缺失或版本冲突

典型报错：

ClassNotFoundException
NoClassDefFoundError

✅ 检查依赖（Spring Boot）：

<dependency>
  <groupId>org.mybatis.spring.boot</groupId>
  <artifactId>mybatis-spring-boot-starter</artifactId>
</dependency>

• MyBatis 和 MyBatis-Spring 版本不匹配
• 同时存在 MyBatis 和 JPA 冲突

4️⃣ application.yml / properties 配置错误

典型报错：

Failed to configure a DataSource

✅ 检查：

mybatis:
  mapper-locations: classpath*:mapper/*.xml
  type-aliases-package: com.xxx.entity

常见错误：

• mapper-locations 写错
• XML 没打进 jar 包

二、数据库 & 数据源问题

5️⃣ 数据库连接失败

典型报错：

Communications link failure
Access denied for user

✅ 检查：

• 用户名/密码
• URL 是否正确
• 数据库是否启动
• 时区问题（MySQL 8）

url: jdbc:mysql://localhost:3306/db?serverTimezone=Asia/Shanghai

6️⃣ 多数据源配置错误

• 没指定 @Primary
• SqlSessionFactory 配置冲突

三、XML / SQL 问题

7️⃣ XML 语法错误

典型报错：

Error creating document instance

✅ 检查：

• 标签未闭合
• 使用了 < 没转义

<if test="age < 18">

应写成：

<if test="age < 18">

8️⃣ ResultMap / 字段映射错误

• 数据库字段和实体类不一致
• 没开启驼峰：

mybatis:
  configuration:
    map-underscore-to-camel-case: true

四、你可以直接这样发我信息

如果你愿意，把下面信息发我，我可以直接帮你定位：

1. 完整报错日志（前 20~30 行）
2. 使用的：
   • Spring Boot 版本
   • MyBatis 版本
3. Mapper 接口 + XML 示例
4. 启动类 / 配置类代码

✅ 总结一句话：

MyBatis 启动报错，99% 是 Mapper 没扫到、XML 不对、配置写错。

你可以把报错贴出来，我帮你一行一行看。