Gradle中配置@AutoService的注解处理器未执行问题咨询

安全阿岳

2026-8-28

核心原因

90%的场景是注解处理器和业务代码写在了同一个Gradle模块。javac执行注解处理逻辑是在编译流程的最早期，此时当前模块的代码还未完成编译、META-INF下的服务注册文件也还没生成，javac根本无法加载到当前模块里的处理器类，哪怕编译后期能看到生成的服务文件，也不会被识别到。
注解处理器本身的配置不符合规范：比如处理器类不是public类型、没有无参public构造器、是普通非静态内部类、@SupportedAnnotationTypes配置的注解全类名错误、@SupportedSourceVersion指定的源码版本和当前使用的JDK版本不匹配，这些问题都会导致javac实例化处理器失败，且默认静默跳过不抛出明显错误。
AutoService依赖版本问题：你用的1.0-rc5是预览版，存在高版本JDK（JDK9+）兼容性bug，可能出现服务文件生成正常，但处理器加载时因为访问限制、类版本错误被拦截的问题。
Gradle编译配置错误：比如手动配置了proc = 'none'关闭了注解处理器自动发现，或者没有将处理器所在的模块/jar包加入annotationProcessor路径，仅加到了implementation/compileOnly路径下，编译期不会去加载路径下的处理器。
生成的服务注册文件内容错误：虽然文件存在，但里面写的处理器全类名拼写错误、存在乱码、多余换行，javac读取后找不到对应类，自然不会执行。

解决步骤

按顺序排查即可：

优先拆分独立模块
把自定义注解处理器、自定义注解的代码单独拆成独立Gradle模块，不要和业务代码混放。典型的模块结构和配置参考：
- my-annotations模块：只存放自定义注解，配置为给消费端依赖
- my-annotation-processor模块：存放注解处理器逻辑，依赖my-annotations模块和AutoService，配置如下：
```
dependencies {
    implementation project(':my-annotations')
    // 替换rc预览版为正式稳定版
    annotationProcessor 'com.google.auto.service:auto-service:1.0.1'
    compileOnly 'com.google.auto.service:auto-service:1.0.1'
}
```
- 业务消费模块：依赖注解模块，同时把处理器模块加到注解处理器路径
```
dependencies {
    implementation project(':my-annotations')
    annotationProcessor project(':my-annotation-processor')
}
```
校验处理器类的基础配置
- 处理器类必须是public修饰，提供public无参构造方法，如果是内部类必须加static修饰
- 检查@SupportedAnnotationTypes里填写的注解全限定名完全正确，需要匹配所有注解可以填"*"
- 给处理器加上和当前JDK版本匹配的@SupportedSourceVersion注解，比如JDK17对应@SupportedSourceVersion(SourceVersion.RELEASE_17)，不要用过低的版本号
- 打开生成的META-INF/services/javax.annotation.processing.Processor文件，确认里面写的处理器全类名和实际类路径完全一致，无拼写错误、乱码、多余空行。
修复Gradle编译配置
- 检查所有Java编译任务的配置，不要添加options.proc = 'none'配置，该配置会直接关闭注解处理器的自动发现和执行
- 给编译任务添加调试参数，执行构建时可以直接看到处理器加载、执行的详细日志，快速定位失败原因：
```
tasks.withType(JavaCompile) {
    options.encoding = "UTF-8"
    options.compilerArgs += ["-XprintProcessorInfo", "-Xlint:processing"]
}
```
高版本JDK适配
如果使用JDK16+版本，除了升级AutoService到1.0.1及以上稳定版，不要给注解处理器路径下的依赖添加模块化强封装限制，拆分独立模块后处理器会走注解处理器专用类加载器，不会触发JPMS的访问拦截。

内容的提问来源于stack exchange，提问作者aminbhst