本文详解 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+ 强制要求通过 <annotationprocessorpaths></annotationprocessorpaths> 显式声明处理器所在的 独立 artifact（jar 包），而非仅靠 <annotationprocessors></annotationprocessors> 列出类名。这是 JSR-269 规范在构建工具层面的强制约束。
以下为标准配置示例（适配 JDK 17+ 与 maven-compiler-plugin:3.8.1+）：
Miller (mlr) 是一个命令行工具，用于查询、整形和重新格式化名称索引数据，如 CSV、TSV、JSON 和 JSON Lines。它将 awk、sed、cut、join 和 sort 的功能整合到一个专为结构化数据处理而构建的单一工具中。
<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模块，并发布至本地/私有仓库。主项目通过<dependency></dependency>或<annotationprocessorpath></annotationprocessorpath>引入该 jar。此举彻底规避“处理器未编译即被调用”的时序冲突。禁止将处理器与业务代码混在同一 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，末尾无空行）
❌ 常见误区与反模式
| 错误方式 | 问题说明 |
|---|---|
仅配置 <annotationprocessors></annotationprocessors> 而无 <annotationprocessorpaths></annotationprocessorpaths>
|
Maven 3.5+ 忽略该配置，处理器不会被加载 |
将处理器类写在 src/main/java 且未分离模块 |
编译阶段 target/classes 尚未生成，ServiceLoader 查找不到类 |
使用 maven-processor-plugin 替代 maven-compiler-plugin
|
该插件已过时（BSB 维护终止），且与现代 JDK 兼容性差，应统一使用 maven-compiler-plugin 的原生 APT 支持 |
在 <dependencies></dependencies> 中声明 provided 或 compile 作用域的处理器 |
仅声明依赖不等于启用处理器；必须通过 <annotationprocessorpaths></annotationprocessorpaths> 显式注册 |
✅ 总结
Annotation Processor not found 不是类路径问题，而是 Maven 构建生命周期与注解处理机制的契约问题。正确解法始终是：
? 物理分离处理器模块（推荐）或确保其 jar 可被 annotationProcessorPaths 定位；
? 显式配置 <annotationprocessorpaths></annotationprocessorpaths>，而非依赖隐式扫描；
? 同步配置 IDE 注解处理开关与 Maven 插件参数；
? 统一使用 maven-compiler-plugin（≥3.8.1）作为唯一 APT 入口，兼容 Lombok、MapStruct、自定义 APT 等全部主流场景。
遵循此方案，即可一劳永逸解决 “Processor not found” 类错误，同时无缝支持 @Slf4j、@Data 等开发必备功能。
