Mybatis-plus找不到Mapper接口？排查Spring Boot启动失败的常见原因与解决方案

如果你正在经历 Spring Boot 启动失败，日志里抛出一大串红色异常，提示说找不到 Mapper 接口，先别急着砸电脑。这个问题在 Mybatis-plus 项目中出现的频率非常高，我几乎每周都能在技术群里看到有人问。而且有意思的是，90% 的情况并不是业务代码写错了，而是扫描路径、注解配置或模块依赖没配对。这篇文章我把这类问题的常见原因、排查思路、解决方案完整梳理一遍，从最简单的情况到多模块工程的复杂场景都覆盖到，争取让你看完之后能一次性解决。

这个问题有个很迷惑的地方：报错信息五花八门，有人看到的是 “No qualifying bean of type 'com.xxx.mapper.UserMapper'”，有人看到的是 “Invalid bound statement (not found): com.xxx.mapper.UserMapper.selectPage”，还有人看到的是 “Field userMapper in com.xxx.service.impl.UserServiceImpl required a bean of type 'com.xxx.mapper.UserMapper' that could not be found”。虽然文本不一样，但它们本质上都指向同一件事——Spring 容器里根本没有那个 Mapper 的 Bean 定义，或者有 Bean 定义但 Mybatis 没法给它绑定 SQL。

所以，要解决这个问题，最关键的一步是搞清楚 Spring 和 Mybatis-plus 到底是怎么把 Mapper 接口变成可注入的对象的。

1. 先搞清楚：Mybatis-plus 无法找到 mapper 接口时，报错到底长什么样

1.1 最常见的两类报错信息区分

在开始排查之前，我建议你先仔细看一眼控制台里的报错内容，因为不同报错对应的排查方向差别很大。

第一类报错是 Spring 容器层面的，典型文本长这样：

*************************** APPLICATION FAILED TO START *************************** Description: Field userMapper in com.example.service.impl.UserServiceImpl required a bean of type 'com.example.mapper.UserMapper' that could not be found. The injection point has the following annotations: - @Autowired(required=true) Action: Consider defining a bean of type 'com.example.mapper.UserMapper' in your configuration.

或者是：

Parameter 0 of constructor in com.example.service.impl.UserServiceImpl required a bean of type 'com.example.mapper.UserMapper' that could not be found.

这类报错的核心信息是 “required a bean of type ... that could not be found”，意思是 Spring 在启动时做依赖注入，发现UserService里有个UserMapper字段要注入，但容器里没有这个类型的 Bean。

第二类报错是 Mybatis 运行层面的，典型文本是：

org.apache.ibatis.binding.BindingException: Invalid bound statement (not found): com.example.mapper.UserMapper.selectPage

这类报错的意思是：Mapper 接口本身已经被扫描到了，Spring 容器里也有代理对象，但是 Mybatis 在解析 Mapper 接口时，发现接口里声明的方法找不到对应的 SQL 语句。

区分这两类报错很重要，第一类要找的是“为什么没被扫描到”“为什么没注册成 Bean”，第二类要找的是“为什么 XML 没绑定上”或“注解 SQL 没解析出来”。

1.2 为什么 Spring 会报“找不到这个 Bean”

很多人不理解：明明我的 Mapper 接口写了@Mapper注解，为什么 Spring 还找不到？

问题出在 Mybatis-plus 对 Mapper 接口的处理方式上。Mapper 接口本身是一个接口，Spring 默认不会为接口创建 Bean。Mybatis-plus 通过@MapperScan注解或@Mapper注解触发扫描，把每个 Mapper 接口动态生成一个代理对象（MapperProxy），然后通过FactoryBean的形式注册到 Spring 容器里。

所以，“找不到 Bean”这件事本质上是：扫描器没有扫描到你的 Mapper 接口，或者扫描到了但没有成功注册。只要顺着这条线索往下查，问题基本都能定位。

2. 最常见的 4 个坑：扫描路径、注解、依赖、编译产物

2.1 启动类位置和扫描路径不匹配

这是最最最常见的坑，没有之一。

@SpringBootApplication注解默认会扫描启动类所在包以及所有子包。这句规则看起来很简单，但实际项目中非常容易踩雷。

举个例子，假设你的项目结构是这样：

com.example.demo ├── DemoApplication.java // 启动类，在 com.example.demo 下 ├── controller ├── service └── mapper

如果DemoApplication.java在com.example.demo包下，UserMapper在com.example.demo.mapper包下，那么默认扫描可以扫到，正常情况下不会出问题。

但很多实际项目的结构是这样的：

com.example ├── admin │ ├── AdminApplication.java // 启动类，在 com.example.admin 下 └── common └── mapper └── UserMapper.java // Mapper 在 com.example.common.mapper 下

这时问题就来了。AdminApplication默认扫描的是com.example.admin包及其子包，根本不会去扫描com.example.common.mapper。Spring 容器里自然没有UserMapper这个 Bean，启动时就会报 “required a bean of type ... that could not be found”。

解决方式有两种：

第一种，在启动类或任意配置类上加上@MapperScan，明确指定要扫描的包路径：

@SpringBootApplication @MapperScan("com.example.common.mapper") public class AdminApplication { public static void main(String[] args) { SpringApplication.run(AdminApplication.class, args); } }

第二种，把@SpringBootApplication的scanBasePackages属性扩展一下：

@SpringBootApplication(scanBasePackages = {"com.example"}) public class AdminApplication { public static void main(String[] args) { SpringApplication.run(AdminApplication.class, args); } }

注意，这两种方式是有区别的。@MapperScan只影响 Mybatis 对 Mapper 接口的扫描，scanBasePackages影响的是 Spring 对所有组件的扫描（Controller、Service 等）。如果你的 Service 也在com.example.common包下，光靠@MapperScan是不够的，还要把scanBasePackages一并配好。

2.2 @Mapper 和 @MapperScan 到底怎么配合

很多新手搞不清楚@Mapper和@MapperScan的关系，这里我一句话总结：

• 如果加了@MapperScan，指定包路径下的所有 Mapper 接口都会自动被扫描注册，接口上不需要再加@Mapper。
• 如果不加@MapperScan，那每个 Mapper 接口都必须显式加上@Mapper注解，否则不会被扫描。
• 两个都加也不会冲突，@MapperScan范围更大，是更推荐的做法。

还有一个细节：@MapperScan支持写多个包路径，也支持通配符。

@MapperScan({"com.example.mapper", "com.example.common.mapper"})

或者扫描一个父包，让所有子包都覆盖到：

@MapperScan("com.example.**.mapper")

这里的**是 Mybatis 扫描器支持的 Ant 风格通配符，*.mapper只管一层，**.mapper可以匹配多层目录。

在实际项目中，我会明确建议：统一走@MapperScan，不要依赖@Mapper。原因很简单，在一个有几十个 Mapper 接口的项目里，如果每个人都记得在接口上加@Mapper，那没问题；但只要有人忘了加，就会出现今天讨论的这个报错。用@MapperScan一次性扫一片，省心得多。

2.3 Mapper 接口所在的包没有被当前模块依赖

这个问题在多模块工程里尤其突出。很多公司项目都会拆成好几层，大概长这样：

parent ├── demo-common // 公共模块：实体类、Mapper 接口 ├── demo-service // 业务模块：Service 实现 └── demo-web // Web 启动模块：Controller、启动类

常见的错误是：UserMapper接口写在demo-common模块里，但demo-web模块的pom.xml只依赖了demo-service，而demo-service的pom.xml里没有声明依赖demo-common，或者声明了但漏了。这样一来，demo-web启动时，demo-common里的UserMapper.class根本不在 classpath 中，Spring 扫描的时候自然找不到。

这种场景的排查方法很明显：在demo-web模块的pom.xml里加上对demo-common的依赖：

<dependency> <groupId>com.example</groupId> <artifactId>demo-common</artifactId> <version>${project.version}</version> </dependency>

如果你直接依赖了demo-service，而demo-service内部依赖了demo-common，那最好是确认一下demo-service的 pom 里有没有把demo-common的 scope 设置成optional或者provided。如果设置了，依赖就不会传递到更上层的demo-web模块里，也会出现类似问题。

用一个命令可以快速验证类是否在 classpath 中，在项目根目录执行：

mvn dependency:tree

然后看输出里有没有demo-common的依赖记录。如果看不到，说明确实没有引进来。

2.4 编译产物问题：target 目录里的 class 没更新

这个坑看起来很低级，但发生频率很高，尤其是老项目。具体现象是：代码明明没问题，@MapperScan也加了，依赖也引了，但启动还是报找不到 Mapper。

大多数时候是 IDE 的增量编译出了问题，target/classes目录下的成旧 class 文件还在，新编译的类没有覆盖进去。或者更离谱的是，整个模块的 class 文件压根没有生成。

遇到这种情况，最直接的办法就是先做一次彻底的清理重编译：

mvn clean mvn compile

或者直接：

mvn clean package -DskipTests

在 IDEA 里也可以直接点Build -> Rebuild Project，或者手动删掉根目录下的target文件夹再重新编译。注意，如果项目里用了 Lombok，还要留意一下 Lombok 插件和注解处理器是否正常工作。很多奇怪的问题（包括编译出来的类不完整、只生成了接口没有生成实现等）都和 Lombok 有关。比如热词里提到的“mybatis-plus多模块 lombok插件”，说明这类组合是很容易出问题的组合。

还有一个小技巧：编译完以后去target/classes目录下看一眼，找到你的 UserMapper.class 文件。如果这个 class 文件存在，说明类本身没问；如果不存在，那问题就出在编译阶段，不用查 Spring 的配置。

3. 若依这类多模块框架遇到此问题的特殊排查法

3.1 为什么若依框架里特别容易踩这个坑

如果你用的是若依（RuoYi）框架，或者基于若依二次开发的项目，这个问题几乎是“必踩坑”的。原因很现实：若依的模块划分比较细，而且启动类所在的包结构和 Mapper 所在的包结构常常不在同一个父包下。

典型的若依模块结构大概是这样的：

ruoyi ├── ruoyi-admin // Web 启动模块 ├── ruoyi-common // 公共模块（很多 Mapper 在这里） ├── ruoyi-framework // 框架配置模块 └── ruoyi-system // 系统模块（也有大量 Mapper）

而启动类RuoYiApplication在ruoyi-admin模块的com.ruoyi包下。虽然看起来都在com.ruoyi下，但若依的项目结构里，很多 Mapper 接口是分散在不同业务 jar 中的，比如ruoyi-system模块里的SysUserMapper，如果在启动时没有通过@MapperScan把ruoyi-system的 mapper 包路径扫进来，那就一定报找不到。

如果是自己单独建的项目仿照若依结构写的，也容易出现同样的情况。因为你把代码搬到了不同的包名下，但只复制了注解配置，没有去适配新的包路径。

3.2 若依框架下的标准配置长什么样

以若依框架为准，它的启动类通常长这样：

@SpringBootApplication(exclude = {DataSourceAutoConfiguration.class}) public class RuoYiApplication { public static void main(String[] args) { SpringApplication.run(RuoYiApplication.class, args); } }

然后 Mapper 的扫描是通过在ruoyi-framework模块的某个配置类上加上@MapperScan来实现的：

@Configuration @MapperScan("com.ruoyi.**.mapper") public class MyBatisConfig { // ... }

注意com.ruoyi.**.mapper这种写法，它表示扫描com.ruoyi包下所有子包里以.mapper结尾的包路径。在若依这种多模块、多业务包的结构下，这么写基本能覆盖所有 Mapper。

如果你把业务代码放到了com.company.business之类的包下，那com.ruoyi.**.mapper就扫不到了，必须加上你自己业务的包路径：

@MapperScan({"com.ruoyi.**.mapper", "com.company.business.**.mapper"})

3.3 多模块启动时报错的完整排查顺序

在多模块工程里遇到这个报错，我建议按以下顺序排查，每一步都很快，可以快速缩小范围：

1. 确认 Mapper 接口所在的模块被当前启动模块依赖了。看pom.xml，或者执行mvn dependency:tree -Dincludes=模块groupId:模块artifactId。
2. 确认启动类上的@MapperScan（如果有）包含了 Mapper 所在的包路径。
3. 确认 Mapper 接口的编译产物存在，去target/classes下找.class文件。
4. 在启动类里临时加一个ApplicationRunner或CommandLineRunner，打印容器里所有 Mapper 相关的 Bean：

@SpringBootApplication public class DemoApplication { public static void main(String[] args) { ConfigurableApplicationContext context = SpringApplication.run(DemoApplication.class, args); String[] beanNames = context.getBeanNamesForAnnotation(Mapper.class); System.out.println("Mapper beans: " + Arrays.toString(beanNames)); } }

这个操作能直接告诉你：Spring 容器里到底注册了哪些 Mapper。如果这个列表是空的，说明扫描器没起作用，问题一定出在扫描配置上。如果列表里有 UserMapper，那问题就可能出在 XML 绑定上，继续看下面一节。

4. XML 映射文件无法绑定：一个容易被误判的“假兄弟问题”

4.1 Invalid bound statement 和找不到 Mapper 的区别

前面提到过，有一部分人报“找不到 Mapper”，实际日志里是Invalid bound statement (not found)。这类问题和“Spring 容器里没有这个 Bean”是两回事，但很多人在网上搜索时把这两类混在一起，容易被误导。

Invalid bound statement的意思是：Mybatis 已经成功扫描到 UserMapper 接口，也生成了代理对象，但当你调用某个方法时，Mybatis 找不到这个方法对应的 SQL。

常见原因有以下几种：

• Mapper 接口对应的 XML 文件没有被加载到 classpath 中。
• XML 文件里 namespace 写错了，和 Mapper 接口的全限定名不一致。
• Mapper 接口方法名和 XML 里的 id 对应不上。
• 接口方法是注解 SQL（如@Select），但 XML 和注解同时存在，在某些配置下导致冲突。

4.2 如何正确配置 mapper-locations

Mybatis-plus 中，XML 文件默认的加载路径是classpath*:/mapper/**/*.xml。如果你的 XML 文件放在src/main/resources/mapper目录下，且文件名例如UserMapper.xml，那么一般不需要额外配置。

但如果你的 XML 文件放在其他目录，或者你的多模块工程里 XML 散落在各个 jar 包中，就必须显式配置：

mybatis-plus: mapper-locations: - classpath*:mapper/**/*.xml - classpath*:/com/example/**/mapper/**/*.xml

注意classpath*:和classpath:的区别。classpath:只会从当前 classpath 中找一个匹配的文件，classpath*:则会扫描所有 jar 包中的 classpath 路径。多模块工程里，Mapper 的 XML 经常在各模块的 jar 包中，用classpath*:会更稳妥。

还有一个特殊情况：Mapper 接口在demo-common模块的com.example.common.mapper包下，XML 文件也放到了同一个包目录下——比如src/main/java/com/example/common/mapper/UserMapper.xml。这种放法有一个大坑：Maven 默认不会把src/main/java目录下的 XML 文件打进产物中。你必须在pom.xml里增加配置：

<build> <resources> <resource> <directory>src/main/java</directory> <includes> <include>**/*.xml</include> </includes> </resource> </resources> </build>

不过说实话，我不建议把 XML 放到 java 目录下。统一放到src/main/resources里，用mapper/目录管理，后续找问题和维护都会轻松很多。

4.3 不用 XML，纯注解的时候为什么也会报绑定失败

有一些场景下，你的 Mapper 接口根本没有对应的 XML 文件，方法上直接用了@Select注解：

public interface UserMapper extends BaseMapper<User> { @Select("SELECT * FROM user WHERE id = #{id}") User selectByIdCustom(Long id); }

这种情况下如果也报Invalid bound statement，常见原因有两种。

第一种：Mybatis-plus在解析 Mapper 时，既要在 XML 中找方法对应的 SQL，也允许从注解中读取 SQL。如果 XML 里没有这个方法，而注解里的 SQL 因为某种原因没被识别（比如同时引入了mybatis-plus-boot-starter和原版mybatis-spring-boot-starter，导致两个 Mybatis 版本打架），就会报找不到绑定。

第二种：使用了 Lombok 的@Builder或@Accessors(chain = true)，导致 Mybatis 反射生成实体的 MetaObject 时某些属性 getter/setter 不存在，从而在解析 Mapper 方法时出现异常，表象上也会接近绑定失败。

所以我才建议，当Invalid bound statement出现时，第一件事不是马上改 XML 配置，而是先确认项目中是不是只引入了一个 Mybatis 依赖。如果同时引入了：

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

那毫无疑问，必然出问题。删掉其中一个，只保留mybatis-plus-boot-starter，问题就会消失。

5. 一套可直接照做的排查手册：从最快到最全

5.1 两分钟快速定位法

如果只想快速解决问题，我建议你按下面这个清单走，每一步确认时间不超过三十秒：

1. 找到报错里提示的 Mapper 接口（比如UserMapper）。
2. 看你的项目里有没有使用@MapperScan。有，看它的包路径是否覆盖了 UserMapper 所在的包。没，去检查 UserMapper 接口上有没有@Mapper注解。
3. 检查 UserMapper 所在的模块是否被启动模块依赖。
4. 执行mvn clean，然后重新启动项目。

这一套走下来，绝大多数情况都能解决。如果还没解决，继续往下走。

5.2 用 ApplicationContext 做一次“体检”

如果你不想靠猜，我教你一个直接看到真相的方法。在启动类里临时加几行代码，把 Spring 容器里所有 Mybatis 相关的 Bean 打印出来，一眼就能看出有没有扫描到 Mapper：

@SpringBootApplication public class DemoApplication implements ApplicationRunner { @Autowired private ApplicationContext applicationContext; public static void main(String[] args) { SpringApplication.run(DemoApplication.class, args); } @Override public void run(ApplicationArguments args) { Map<String, Object> mapperBeans = applicationContext.getBeansWithAnnotation(Mapper.class); System.out.println("Mapper beans size = " + mapperBeans.size()); mapperBeans.forEach((k, v) -> System.out.println(" - " + k + " -> " + v.getClass().getName())); } }

如果你发现mapperBeans.size()是 0，说明 Mybatis 完全没扫描到你的 Mapper 接口，返回去查@MapperScan路径。如果有 UserMapper，但启动还是报错，那问题转移到了 XML 绑定或依赖注入层面。这时候再把注意力放到mapper-locations配置和Invalid bound statement那类问题上去。

5.3 日志级别临时调高，看 Mybatis 扫描日志

还有一个很实用的方式：把logging.level.com.baomidou.mybatisplus和logging.level.org.apache.ibatis调成 DEBUG，然后重新启动。Mybatis 扫描器在 DEBUG 模式下会打印它扫描了多少个接口、分别是什么。这样你就能从日志里直观地看到扫描范围是否包含理想的包路径。

logging: level: com.baomidou.mybatisplus: debug org.apache.ibatis: debug

不过要注意，日志量大，平时不要开着 DEBUG 跑生产环境，只在排查时临时开一下。

6. 常见问题速查表：按报错场景直接对号入座

为了方便查阅，我把这类“找不到 mapper 接口”相关的典型场景整理成一个表格，你可以按自己的实际情况快速定位。

这个表格基本覆盖了我在实际工作中遇到过的全部情况。如果你按表格对号入座后还没解决，那大概率是你项目里有某个特殊的自定义配置在捣乱，这时候就要去看启动过程的完整日志了。

7. 排查这类问题的3点个人心得

最后分享几个我自己的习惯，虽然不能解决所有问题，但能帮你减少踩这类坑的概率。

第一，我建议所有新项目的启动类都加上@MapperScan，并且扫描路径写得尽量精确，不要为了省事直接写个根包名。根包名确实能覆盖所有 Mapper，但会导致启动时多扫描很多无关的包，而且如果以后换了包结构，排查起来更麻烦。

第二，Mapper 接口的 XML 文件一定要放到 resources 目录下，并且路径结构尽量和接口包名一致。比如UserMapper在com.example.mapper包，那么 XML 就放在resources/mapper/UserMapper.xml，然后用classpath*:mapper/**/*.xml加载。这是最不容易出错的组合。

第三，遇到问题别急着百度复制代码。先把@MapperScan路径、pom 依赖、编译产物三件事验证一遍，比盲目改配置有效得多。我见过太多人往启动类上塞各种 @EnableXxx 注解，结果问题反而越改越乱。

根据我个人的经验，绝大多数“Mybatis-plus 无法找到 mapper 接口”的求助帖，最后基本上都是扫描路径或模块依赖的问题，解决方案就是我上面写的这些。如果照着这文章排查一遍还找不到问题，那就把启动日志完整发出来，上面每一行红字都有它的含义，一条条拆开看，一定能定位到根因。