本文详解 maven-compiler-plugin 中 Annotation Processor not found 错误的根本原因与专业级修复方案，涵盖自定义 APT、Lombok、MapStruct 等场景，重点解决处理器类存在却无法加载的核心矛盾。
本文详解 `maven-compiler-plugin` 中 `annotation processor not found` 错误的根本原因与专业级修复方案，涵盖自定义 apt、lombok、mapstruct 等场景，重点解决处理器类存在却无法加载的核心矛盾。
在 Maven 项目中使用注解处理器（Annotation Processor，APT）时，常见错误如 error: annotation processor com.example.MyProcessor not found，表面看是类路径缺失，实则根源在于 编译阶段的依赖可见性与时序问题：maven-compiler-plugin 在执行 compile 阶段时，无法自动感知当前模块（或未编译完成的模块）中定义的处理器类——即使 META-INF/services/javax.annotation.processing.Processor 文件正确存在，JVM 的 ServiceLoader 也无法加载尚未编译进 target/classes 的类。
✅ 正确做法：显式声明 annotationProcessorPaths
Maven 3.5+ 及 maven-compiler-plugin 3.5+ 强制要求通过
以下为标准配置示例（适配 JDK 17+ 与 maven-compiler-plugin:3.8.1+）：
Java Maven 项目审查工作流的通用输入处理。当 Java Maven 项目以 ZIP压缩包或 GitLab 仓库 URL 形式提供且需要...时使用。
<build><plugins><plugin><groupid>org.apache.maven.plugins</groupid><artifactid>maven-compiler-plugin</artifactid><version>3.11.0</version><!-- 推荐使用 3.11.0 或更高稳定版 --><configuration><source>17</source><target>17</target><!-- ✅ 关键：声明处理器所在 jar 的坐标 --><annotationprocessorpaths><path><groupid>com.example</groupid><artifactid>example-processor</artifactid><version>0.0.1-SNAPSHOT</version></path><!-- ✅ 同时支持 Lombok（如 @Data, @Slf4j） --><path><groupid>org.projectlombok</groupid><artifactid>lombok</artifactid><version>1.18.34</version></path><!-- ✅ 可选：MapStruct 处理器 --><path><groupid>org.mapstruct</groupid><artifactid>mapstruct-processor</artifactid><version>1.5.5.Final</version></path></annotationprocessorpaths><!-- ⚠️ 注意：此处 annotationProcessors 不再必需，但可保留用于显式控制启用顺序 --><annotationprocessors><annotationprocessor>com.example.MyProcessor</annotationprocessor></annotationprocessors><!-- 可选：开启详细日志，便于调试 --><compilerargs><arg>-Amapstruct.verbose=true</arg><arg>-Alombok.addLombokGeneratedAnnotation=true</arg></compilerargs></configuration></plugin></plugins></build>
? 关键原则与最佳实践
分离处理器模块（强烈推荐）
将MyProcessor及其依赖（如javax.annotation.processing.*、com.sun.source.tree.*）单独打包为一个example-processor模块，并发布至本地/私有仓库。主项目通过禁止将处理器与业务代码混在同一 module
若强行共存于同一pom.xml，需通过 Maven profile 控制生命周期（如先mvn compile处理器类，再mvn compile -Papt启用 APT），但极易出错且不可维护。IDE 同步必须启用 Annotation Processing
在 IntelliJ IDEA 中：Settings → Build → Compiler → Annotation Processors → ✔ Enable annotation processing；并确保Obtain processors from project classpath已勾选。Eclipse 用户需安装 Lombok Plugin 并启用 Annotation Processing。-
验证服务文件是否生效（仅限 jar 内部）
若处理器已打包为 jar，请确认其META-INF/services/javax.annotation.processing.Processor文件内容为：com.example.MyProcessor
（注意：换行符为 LF，无 BOM，末尾无空行）
❌ 常见误区与反模式
| 错误方式 | 问题说明 |
|---|---|
仅配置 |
Maven 3.5+ 忽略该配置，处理器不会被加载 |
将处理器类写在 src/main/java 且未分离模块 |
编译阶段 target/classes 尚未生成，ServiceLoader 查找不到类 |
使用 maven-processor-plugin 替代 maven-compiler-plugin
|
该插件已过时（BSB 维护终止），且与现代 JDK 兼容性差，应统一使用 maven-compiler-plugin 的原生 APT 支持 |
在 provided 或 compile 作用域的处理器 |
仅声明依赖不等于启用处理器；必须通过 |
✅ 总结
Annotation Processor not found 不是类路径问题，而是 Maven 构建生命周期与注解处理机制的契约问题。正确解法始终是：
? 物理分离处理器模块（推荐）或确保其 jar 可被 annotationProcessorPaths 定位；
? 显式配置
? 同步配置 IDE 注解处理开关与 Maven 插件参数；
? 统一使用 maven-compiler-plugin（≥3.8.1）作为唯一 APT 入口，兼容 Lombok、MapStruct、自定义 APT 等全部主流场景。
遵循此方案，即可一劳永逸解决 “Processor not found” 类错误，同时无缝支持 @Slf4j、@Data 等开发必备功能。
