为何-proc:none生效而-proc:only报错？Java 17注解处理器疑问

一、-proc:only找不到处理器的核心原因 #

-proc:only的作用是仅执行注解处理器，跳过源代码编译，这要求处理器的字节码必须提前存在于编译类路径中，出现找不到类的错误通常是以下情况：

• 处理器未提前编译：如果处理器和业务代码在同一个模块，-proc:only会跳过编译步骤，此时处理器本身还未被编译成字节码，自然无法在类路径中找到。
• 依赖范围错误：若处理器作为依赖引入，但依赖范围设为provided/test，会导致编译阶段类路径不包含该依赖，无法加载处理器类。建议使用annotationProcessor范围（maven专门为注解处理器提供的依赖范围）。
• 插件版本不兼容：Java 17对注解处理器的类路径、模块化处理有新规范，旧版本maven-compiler-plugin（如3.x早期版本）无法适配，导致无法识别处理器，需升级到3.10.1及以上版本。

二、-proc:none注解仍被处理的原因 #

按官方定义-proc:none应禁用所有注解处理，出现“倒置”现象的常见诱因：

• 未覆盖默认编译任务：maven-compiler-plugin默认会在compile阶段执行编译，若你添加的自定义<execution>未指定正确阶段或未禁用默认任务，默认编译会在无-proc:none参数的情况下执行，注解处理实际是默认任务的结果。
• IDE自动编译干扰：IntelliJ IDEA等IDE的后台自动编译不会严格遵循maven参数，即使maven任务禁用了注解处理，IDE的自动编译可能已经完成了注解处理，导致你误以为参数未生效。
• 其他插件触发处理：项目中若使用Lombok、代码生成类插件，这些插件可能独立于maven-compiler-plugin执行注解处理，不受-proc:none参数控制。

三、正确配置方案 #

1. 独立处理器模块（推荐） #

若处理器是单独模块，在业务模块pom.xml中用annotationProcessor依赖引入：

<dependencies>
    <!-- 引入注解定义 -->
    <dependency>
        <groupId>com.eva</groupId>
        <artifactId>custom-annotation</artifactId>
        <version>1.0.0</version>
    </dependency>
    <!-- 仅编译阶段引入处理器 -->
    <dependency>
        <groupId>com.eva</groupId>
        <artifactId>custom-processor</artifactId>
        <version>1.0.0</version>
        <scope>annotationProcessor</scope>
    </dependency>
</dependencies>

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.11.0</version>
            <configuration>
                <source>17</source>
                <target>17</target>
                <!-- 无需手动指定-proc参数，maven自动处理 -->
            </configuration>
        </plugin>
    </plugins>
</build>

2. 同模块下的处理器配置 #

若处理器和业务代码在同一模块，需分两步编译：先编译处理器，再执行注解处理：

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.11.0</version>
            <executions>
                <!-- 第一步：编译处理器代码 -->
                <execution>
                    <id>compile-processor</id>
                    <phase>process-sources</phase>
                    <goals>
                        <goal>compile</goal>
                    </goals>
                    <configuration>
                        <source>17</source>
                        <target>17</target>
                        <includes>
                            <include>com/eva/CustomAnnotationProcessor.java</include>
                        </includes>
                    </configuration>
                </execution>
                <!-- 第二步：执行注解处理 -->
                <execution>
                    <id>compile-with-processor</id>
                    <phase>compile</phase>
                    <goals>
                        <goal>compile</goal>
                    </goals>
                    <configuration>
                        <source>17</source>
                        <target>17</target>
                        <compilerArgument>-proc:only</compilerArgument>
                        <classpathElements>
                            <classpathElement>${project.build.outputDirectory}</classpathElement>
                        </classpathElements>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

3. 验证-proc:none生效 #

关闭IDE自动编译（如IDEA关闭「Build automatically」），执行mvn clean compile -X查看日志，确认-proc:none参数被传递给javac，且无注解处理器执行记录。

内容的提问来源于stack exchange，提问作者Cristian Jacob Jimenez