报错信息：at org.springframework.beans.factory.support.ConstructorResolver.instantiate(ConstructorResolver.java:646) at org.springframework.beans.factory.support.ConstructorResolver.instantiateUsingFactoryMethod(ConstructorResolver.java:626) at org.springframework.beans.factory.support.AbstractAutowireCapableBeanFactory.instantiateUsingFactoryMethod(AbstractAutowireCapableBeanFactory.java:1352) at org.springframework.beans.factory.support.AbstractAutowireCapableBeanFactory.createBeanInstance(AbstractAutowireCapableBeanFactory.java:1195) at org.springframework.beans.factory.support.AbstractAutowireCapableBeanFactory.doCreateBean(AbstractAutowireCapableBeanFactory.java:582) at org.springframework.beans.factory.support.AbstractAutowireCapableBeanFactory.createBean(AbstractAutowireCapableBeanFactory.java:542) at org.springframework.beans.factory.support.AbstractBeanFactory.lambda$doGetBean$0(AbstractBeanFactory.java:336) at org.springframework.beans.factory.support.DefaultSingletonBeanRegistry.getSingleton(DefaultSingletonBeanRegistry.java:234) at org.springframework.beans.factory.support.AbstractBeanFactory.doGetBean(AbstractBeanFactory.java:334) at org.springframework.beans.factory.support.AbstractBeanFactory.getBean(AbstractBeanFactory.java:209) at org.springframework.beans.factory.config.DependencyDescriptor.resolveCandidate(DependencyDescriptor.java:276) at org.springframework.beans.factory.support.DefaultListableBeanFactory.doResolveDependency(DefaultListableBeanFactory.java:1391) at org.springframework.beans.factory.support.DefaultListableBeanFactory.resolveDependency(DefaultListableBeanFactory.java:1311) at org.springframework.beans.factory.support.AbstractAutowireCapableBeanFactory.autowireByType(AbstractAutowireCapableBeanFactory.java:1519) … 101 common frames omitted Caused by: org.springframework.beans.BeanInstantiationException: Failed to instantiate [org.apache.ibatis.session.SqlSessionFactory]: Factory method 'sqlSessionFactory' threw exception; nested exception is org.apache.ibatis.builder.BuilderException: Error creating document instance. Cause: org.xml.sax.SAXParseException; lineNumber: 1; columnNumber: 1; 前言中不允许有内容。
这个报错是典型的 Spring + MyBatis-Plus 启动时的 XML 解析异常，核心报错是前言中不允许有内容，这是 MyBatis 解析 XML 文件时的典型格式错误，下面为你详细拆解原因和排查解决方案：
一、报错核心根源
这句话的本质是：MyBatis 解析的 XML 文件（Mapper.xml 或 mybatis-config.xml）不符合标准 XML 格式要求，XML 声明（<?xml version="1.0" encoding="UTF-8"?>）前存在多余内容，或 XML 文件本身格式损坏。
其中 “前言” 特指 XML 文件的声明节点（即文件开头的版本 / 编码声明），该声明必须满足 “文件第一行、第一列，无前导任何字符” 的要求。
二、常见问题场景（按优先级排序）
场景 1：XML 文件开头存在多余字符（最常见）
XML 声明（<?xml …?>）前有以下无效字符，导致解析失败：
场景 2：XML 文件编码问题（UTF-8 带 BOM 头）
使用记事本等编辑器保存 UTF-8 编码的 XML 文件时，会自动添加 BOM 头（\\ufeff，三个不可见字节），该字节位于文件最开头，XML 解析器无法识别，误认为是 “前言中的多余内容”。
场景 3：XML 声明格式错误或缺失
场景 4：空白 / 无效 XML 文件
项目中存在空的 XML 文件（无任何内容），或仅包含空白字符的 XML 文件，MyBatis 扫描到该文件时，解析会触发此异常。
场景 5：Mapper.xml 内容损坏或格式违规
XML 标签未闭合、标签嵌套错误、特殊字符未转义（如<、&未处理），间接导致解析器在读取前言后无法正常解析后续内容，抛出此异常。
三、分步排查解决方案
步骤 1：检查所有 MyBatis 相关 XML 文件
重点排查以下文件，按 “最近修改 / 新增” 优先：
步骤 2：规范 XML 文件开头格式
xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" "http://mybatis.org/dtd/mybatis-3-mapper.dtd">
<mapper namespace="com.example.mapper.UserMapper">
<!– 后续内容 –>
</mapper>
步骤 3：解决 UTF-8 BOM 头问题
- IDEA：文件 -> File Encodings -> 勾选Remove BOM，编码选择UTF-8，重新保存；
- Notepad++：格式 -> 选择 “UTF-8 无 BOM 格式”，保存替换原文件。
步骤 4：清理无效 / 空白 XML 文件
步骤 5：校验 XML 文件内容完整性
步骤 6：验证 MyBatis-Plus XML 扫描配置
确认项目中 MyBatis-Plus 的 XML 扫描路径配置正确，避免扫描到非目标 XML 文件：
yaml
# application.yml 示例配置
mybatis-plus:
mapper-locations: classpath:mapper/*.xml # 仅扫描 mapper 目录下的 XML 文件，避免冗余
configuration:
map-underscore-to-camel-case: true
