今天早上我打开项目编译到一半直接甩出一行“Could not load module”把我整懵了。报错信息又短又不给上下文Gradle 日志里翻半天也没看到具体是哪个模块、哪个类出了问题。后来我一层层排查发现这个错误在 Kotlin kapt 的场景里其实有好几个兄弟版本比如Could not load module: module_name、Unable to load class、kapt: Could not load module每个背后的原因都不太一样。这篇文章我不打算写成官方案例的翻译而是把我从“看到报错一头雾水”到“彻底定位并解决”的完整过程拆给你看尤其是 Gradle 8.2.2 下怎么适配 kapt直接给可用的配置。先说结论kapt 报 Could not load module90% 的情况不是 kapt 本身坏了而是 Kotlin 编译器加载注解处理器时出了问题。要么是 JDK 版本和 Gradle 不匹配要么是依赖声明方式不对导致注解处理器没进 classpath要么是 kapt 的 Worker API 在增量编译缓存里拿到了脏数据。知道这个方向之后排查和解决就快多了。这篇文章适合所有被 kapt 折腾过的 Android / Kotlin 开发者特别是刚升级 Gradle 8.x 又被 kapt 崩了一脸的人。1. 报错现象与根因定位1.1 错误信息到底在说什么先看最常见的报错形态Log 大概是这样的e: java.lang.IllegalStateException: Could not load module: org.jetbrains.kotlin.kapt3或者Execution failed for task :app:kaptDebugKotlin. Could not load module: com.example.processor如果是第一种说明 kapt 自身在初始化阶段就失败了。这个阶段发生在 Kotlin 编译器的 annotation processing 环节kapt3 是 Kotlin 内置的注解处理实现模块。它加载不了通常不是代码问题而是环境问题Kotlin 编译器插件没被正确加载、Gradle 插件版本和实际执行的 Gradle 版本不匹配、或者 JDK 模块系统JPMS层面出现了限制。如果是第二种报错的是你自己的注解处理器模块名那就更有意思了。说明 kapt 尝试加载com.example.processor这个 annotation processor但 ClassLoader 里找不到类。这种情况常见于注解处理器是通过implementation而不是kapt引入的、处理器依赖在某个子模块漏传了、或者META-INF/services配置没生效。这里我想先强调一个容易被忽略的点kapt 有独立的 classpath。它不是直接把 annotationProcessor 依赖塞进 app 模块的 compile classpath而是通过 kapt 的专用配置在编译阶段单独组成一个 processor classpath。所以用错配置作用域是“Could not load module”的头号原因。1.2 第一步分清编译阶段与排查顺序看到这个报错先别急着 clean 重新 build。虽然最后大概率要清理一遍但你得先确认问题发生在哪个阶段。kapt 的整体流程分为三步Kotlin 编译器解析并生成 stubJava 桩用于让 Java 处理器能看见 Kotlin 声明的类型结构。将 stub 交给 Java 编译器执行 annotation processing。将处理器生成的代码合并回编译流程再编译真正的 Kotlin 代码。“Could not load module”如果出现在kaptGenerateStubsDebugKotlin任务里说明第一步就失败了大概率跟 kapt 插件自身加载有关。如果出现在kaptDebugKotlin任务里那就是第二步加载处理器失败。你先用下面的命令确认是哪个任务挂了./gradlew :app:kaptDebugKotlin --stacktrace看到任务名之后再按下面的顺序走先查 Kotlin / Gradle / JDK 三者版本组合。再查注解处理器的依赖作用域。然后关掉增量编译试一次。最后清理所有缓存重新构建。1.3 为什么 Gradle 升级后特别容易炸这个报错在 Gradle 8.2.2 下特别高频是有客观原因的。Gradle 8.x 对 Java 工具链、Worker API、编译缓存都做了不少改动而 kapt 的 Kotlin 编译器 embeddable 依赖和 Gradle 内部机制耦合又很深。当你从 Gradle 7.x 升到 8.x 时如果 Kotlin 插件还停留在 1.8.x 甚至更低版本就容易遇到 kapt 无法加载到正确编译器模块的问题。Gradle 8.x 要求 Kotlin Gradle Plugin 的最低版本随之提高。拿 8.2.2 举例Kotlin 1.9.0 是官方测试过比较稳的起始版本。如果你还在用 1.7.21 或 1.8.10还硬要配 Gradle 8.2.2kapt 模块加载失败的概率就会明显变大。这不是玄学是版本兼容矩阵的问题。kapt 作为一个编译器插件运行时要加载 Kotlin 编译器的 class而 Gradle 8 对类加载器的隔离策略更严格了老版本 kapt 在默认类加载模式下可能访问不到它需要的模块。2. 最常见的几个触发来源2.1 Kotlin 插件与 Gradle 版本不匹配这是我在实际项目里遇到最多的原因。很多人升级 Gradle 时习惯直接改gradle-wrapper.properties却忘了同步升级 Kotlin 插件结果 kapt 模块加载失败。一个很典型的组合是Gradle 8.2.2 Kotlin 1.8.0。表面上看 Kotlin 1.8.0 不算老但 Gradle 8.2.2 引入的 worker API 变化会让旧版 kapt 出现类加载问题尤其是启用 configuration cache 的项目。官方后来在 Kotlin 1.8.20 做了不少 kapt 的修复到 1.9.0 才算比较完整地支持 Gradle 8。所以如果你问我最省心的配置我会直接给这套// 项目根目录 build.gradle 或 build.gradle.kts plugins { kotlin(android) version 1.9.22 apply false kotlin(kapt) version 1.9.22 apply false }Gradle 版本用 8.2.2Kotlin 版本用 1.9.22 或 1.9.24。这个组合我跑了多个项目不管是普通 Android 模块还是库模块kapt 都稳定得多。2.2 JDK 版本与编译 target 不一致第二种是环境问题但太容易被忽略。kapt 是在编译器进程里运行的如果你的 Gradle 运行在 JDK 17而项目的compileOptions和kotlinOptions还指着 Java 8其实一般没关系因为 Gradle 会用 toolchain 去调。真正会触发 “Could not load module” 的是Gradle 进程本身跑在一个比较老的 JDK 上比如 JDK 8而 Kotlin 编译器插件需要更高版本的字节码或者反过来。举个真实案例公司的 CI 机器默认 JAVA_HOME 是 JDK 8但本机开发用的是 JDK 17。本机编译正常CI 就是报Could not load module: org.jetbrains.kotlin.kapt3。排查到最后发现Kotlin 1.9.22 编译器的部分类已经需要 JDK 11 才能加载而 Gradle 8.2.2 本身也要求 JDK 8 以上但 kapt 的某些内部类在 JDK 8 上就是会挂。解决方法也简单统一 JDK 版本。最简单的方式是在gradle.properties里指定或者在 CI 上把 JAVA_HOME 切到 JDK 17。如果你不想强依赖 CI 环境可以在项目里用 Java Toolchain// build.gradle.kts kotlin { jvmToolchain(17) }同时把compileOptions保持为一个稳定目标比如 Java 11 或 17避免 Kotlin 编译器和 Java 编译器拿到不同的 target 信息导致模块解析异常。2.3 注解处理器依赖缺失或传递依赖冲突这个原因更偏向“代码层面”。很多人会把 kapt 依赖写错最常见的是implementation(com.google.dagger:dagger-compiler:2.48) kapt(com.google.dagger:dagger-compiler:2.48)这里的问题在于implementation会把dagger-compiler也放进 app 的运行时 classpath但这个库本身是注解处理器不应该出现在运行时。更隐蔽的问题是有些时候你只写了implementation(xxx:processor:1.0)却忘了写kapt(xxx:processor:1.0)然后 kapt 阶段就报加载不了 processor。另一个常见情况是传递依赖搞丢了。比如你有一个自己的注解处理器模块processor其中声明了api(com.squareup:javapoet:1.13.0)。正常来说这个依赖会随着kapt(project(:processor))传递到处理器 classpath。但如果你在processor模块里用了implementation而处理器的代码运行时需要 javapoet 的类就会在 kapt 加载时可能出现NoClassDefFoundError或间接触发Could not load module。建议检查两个地方第一所有注解处理器统一用kapt配置声明第二处理器模块自身的依赖如果处理器代码直接引用了应该用api而不是implementation。2.4 缓存与增量编译的脏数据第三种当你确认上面的配置都正确时可能就轮到缓存问题。Gradle 的构建缓存、Kotlin 的增量编译缓存、还有 kapt 自己的 stub 缓存都有可能带来这种灵异现象。典型场景是你之前在一个旧版本组合下编译成功之后升级了 Kotlin 或 Gradle没有 clean 就直接 build。旧的增量编译数据里记录了旧版本的 kapt 类型信息新的 kapt 加载时发现信息对不上直接抛出模块加载失败。这个问题在“改一行代码重新编译”时会暴露但当你执行clean之后又神奇地好了。很多人就这样以为解决了其实只是掩盖了根因。如果你频繁遇到“clean 后好一阵过几天又出现”说明增量编译配置和你的实际依赖结构有冲突。这时你应该考虑关掉 kapt 的增量编译或者至少验证一下是否增量编译导致。3. Gradle 8.2.2 适配方案3.1 明确各组件版本组合我知道很多人看到版本矩阵就头疼所以我直接给一个我目前在用的、经过验证的版本组合。注意这不是唯一答案但它是能让你避免大量无谓排查的答案。组件推荐版本说明Gradle8.2.2针对本主题的基准版本Android Gradle Plugin8.2.2与 Gradle 8.2.2 官方兼容Kotlin Gradle Plugin1.9.22对 Gradle 8 支持成熟的版本JDK17Gradle 8 官方推荐的运行版本compileOptions / targetJava 11 或 17建议统一避免工具链差异AGP 8.x 已经不支持 JDK 8 编译所以如果你还在用 JDK 8 跑 Android 项目升级 Gradle 8.2.2 之前最好先把 JDK 切到 17。别想着偷懒AGP 8.2 的默认行为里很多任务已经要求 JDK 17。3.2 kapt 配置的推荐写法在 Gradle 8.2.2 下kapt 的配置建议显式设置这些内容。以build.gradle.kts为例plugins { id(com.android.application) id(org.jetbrains.kotlin.android) id(org.jetbrains.kotlin.kapt) } android { compileOptions { sourceCompatibility JavaVersion.VERSION_17 targetCompatibility JavaVersion.VERSION_17 } } kotlin { jvmToolchain(17) } kapt { // 使用 kapt2 替代旧的 kapt1 实现 useBuildCache true // 如果开启增量编译后出现诡异问题先关掉它 javacOptions { option(-Xmaxerrs, 500) } }这里特别说明一下useBuildCache。它控制的是 kapt 的构建缓存不是 Kotlin 的增量编译。这个开关在 Gradle 8.2.2 下可以正常开启前提是你的 Gradle 构建缓存本身没有问题。如果发现 clean 之后还一直报错先把这个改成false再试。另外很多人忘了设置kapt.include.compile.classpath这个参数。它的作用是让 kapt 在处理注解时是否能读取 compile classpath 里的类。默认是false在某些场景下会导致处理器扫描不到依赖的类从而抛出类似模块加载失败的异常。如果你自己写注解处理器并且它需要读取非 kapt 依赖中的注解可以加上kapt { arguments { arg(kapt.include.compile.classpath, true) } }但要注意这会降低编译速度因为它把整个 compile classpath 都交给处理器扫描。不是所有项目都需要看你自己处理器的实现。3.3 关闭 Worker API 与隔离问题的处理Gradle 8 默认开启了隔离的 Worker APIkapt 也受这个影响。报错日志里如果你看到类似Could not load module的同时伴随worker daemon或classloader字样那基本可以判断是 Worker API 的类加载隔离导致的。有一个临时但很好用的办法在gradle.properties里关掉 kapt 的 worker 隔离功能kapt.use.worker.apifalse这个属性可以强制 kapt 不通过 Worker API 运行直接在当前编译进程中执行。这样做的好处是绕开了类加载隔离问题坏处是编译时占用的内存会上升而且 keystore 之类的并发问题也可能出现。所以它更适合作为短期绕过方案而不是长期配置。如果你想长期解决还是得回到版本组合上。把 Kotlin 插件升到 1.9.22 之后Worker API 的类加载问题基本已经修掉不需要再关。4. 实操排错流程4.1 快速定位哪一个模块加载失败当你有多个模块时kapt 报错经常不告诉你具体是哪个模块的哪个处理器。所以第一步是用精确任务名定位。假设你的项目有app、lib-core、lib-processor这三个模块报错发生在:app:kaptDebugKotlin但具体是哪个处理器加载失败需要看更详细的日志./gradlew :app:kaptDebugKotlin --info在--info日志里搜索kapt相关的 classpath 输出。你会看到一个类似这样的列表kapt classpath: /path/to/processor.jar:/path/to/javapoet.jar:...如果你看到你的 processor jar 不在这个列表里那问题就是依赖没被正确声明。如果列表里有但还是报Could not load module那接下来要看META-INF/services文件是否存在。一个很小的坑有些注解处理器库会打出 fat jar把所有依赖打在一起但META-INF/services里的类名写错了或者类名混淆了。这种情况下处理器在 kapt 加载阶段就会失败。你可以直接在 gradle 命令后加--debug并搜索Could not load前面的类名再去 jar 里验证jar tf processor.jar | grep META-INF/services如果没有输出说明你依赖的库没带服务描述文件这时候需要手动声明 processorkapt { correctErrorTypes true javacOptions { option(-processor, com.example.MyProcessor) } }4.2 清理与重试的正确姿势清理不等于./gradlew clean就完事了。kapt 的具体缓存有时候藏在.gradle目录里clean 任务不会清除到那么深。所以遇到诡异报错时我按这个顺序来./gradlew --stop ./gradlew clean rm -rf ~/.gradle/caches/build-cache-1 rm -rf ~/.gradle/caches/kotlin-dsl rm -rf .gradle./gradlew --stop是停止所有 Gradle daemon这一步很多人会漏掉。kapt 的编译器进程是常驻的如果你升级了 Kotlin 插件但没重启 daemon可能还在用旧的编译器 class加载自然会出问题。如果你在 CI 上也遇到同样问题建议在 CI 流程里增加一步缓存清理策略只在gradle-wrapper.properties发生变化时清空 build cache而不是每次都全量清理。全量清理太慢了不利于开发效率。4.3 使用命令行日志定位关键线索当你启用--info之后会看到很多无意义的输出所以要有技巧地过滤。我一般用这样的命令./gradlew :app:kaptDebugKotlin --info 21 | grep -i could not load\|classpath\|kapt | head -80这里加了head -80是为了避免日志太多被刷屏。在输出里重点看三行内容kapt classpath这一行确认处理器依赖是否出现在 classpath 里。报错信息前面最后几行看是否有ClassNotFoundException或NoClassDefFoundError。Caused by:后面的内容这往往才指向真正的底层问题。很多人只看最上面红色那行Could not load module就停了其实真正的原因在下面的Caused by链里。我见过一个案例最上面是模块加载失败但Caused by是一个ZipException: invalid CEN header说明某个 jar 文件损坏了——重下依赖后彻底解决。这跟配置半毛钱关系都没有。5. 常见问题速查表与避坑经验5.1 高频问题对照表我在收尾前把高频问题整理成一个速查表方便你直接对照报错形态常见根因第一优先处理动作Could not load module: org.jetbrains.kotlin.kapt3Kotlin 插件版本与 Gradle 不兼容升级 Kotlin 到 1.9.22Could not load module: com.example.Processorkapt 依赖未声明或 classpath 缺失检查是否用了kapt(...)报错伴随ClassNotFoundException处理器内部依赖缺失用api替代implementation传递依赖Could not load module 构建缓存命中后出现缓存数据过期清理 build cache必要时关闭useBuildCache升级 Gradle 后高频出现clean 后暂时消失增量编译存量数据损坏关掉 kapt 增量编译重启 daemon同时报 Worker daemon 类错误Worker API 隔离问题临时设置kapt.use.worker.apifalse这张表不敢说覆盖所有场景但覆盖了我遇到过的 95% 情况。记住排错时最好一次只改一个变量。不要同时升级 Kotlin、改 kapt 配置、又换 JDK这样出了问题你根本不知道是哪个变量引起的。5.2 几条我踩过坑之后的经验最后分享几条实际操作中得来的经验。第一不要只在 app 模块里配置 kapt。如果你的项目有 library 模块并且那个模块也有注解处理器那么每个模块都要单独声明kapt(...)依赖。kapt 不会把 app 模块的处理器 classpath 传递给 library 模块这是很多人忽略的。我曾在lib-network里用了 Room但在根模块只给app配了 kapt结果lib-network构建时随机出现处理器加载失败。给每个需要的模块补上之后就好了。第二kapt和implementation不要混用同一个注解处理器依赖。如果你不小心写成了implementation(com.google.dagger:dagger-compiler:2.48)记得删掉。dagger-compiler 只需要出现在 kapt 配置里。混用会让处理器类同时出现在编译和运行时 classpath表面上不影响编译但当你用 R8 或 ProGuard 开启混淆后可能会出现类重复或加载错误排查起来非常痛苦。第三遇到问题先看gradle版本与kotlin插件版本是否存在已知兼容矩阵。我一般在根目录建一个VERSIONS.md记录当前项目锁定的 Gradle、AGP、Kotlin、JDK 四个版本。每次升级只动一个并记录日期和现象。几次下来你会发现大多数构建问题都能快速定位到某一个版本的变更上。第四如果手头项目比较大注释处理器特别多建议把 kapt 的增量缓存定期清一次。不是每次 build 都清而是每周或者每两周执行一次./gradlew clean rm -rf .gradle这个操作可以预防很多“没有改代码却在某天突然编译不过”的问题。项目越大kapt 的缓存越容易积累脏数据。第五实在不行的时候考虑迁移到 KSP。Kotlin 官方已经在推动 KSP 取代 kapt很多大库如 Room、Hilt 都已经支持 KSP。KSP 的类加载和增量编译机制比 kapt 干净很多几乎没有“Could not load module”这种抽象报错。从 kapt 切到 KSP 的成本不算高改动主要集中在依赖声明与处理器参数配置上。如果你维护的老项目刚好在升级 Gradle不如直接把 kapt 一并换掉省得以后再被这种报错折磨。