Android项目在GitHub Actions Ubuntu runner构建失败（Kapt类找不到）

问题场景 #

我的Android应用模块里，部分类由Kapt编译时生成，存放路径为build/generated/source/kapt/com/myproject/myapp/。本地MacOS和Ubuntu环境构建都正常，能正常访问这些生成类；但用GitHub Actions的Ubuntu runner构建时就失败，报错找不到生成类（比如import com.myproject.myapp.MyGeneratedClass;这行提示找不到符号），换成MacOS runner则构建正常。已确认两边环境一致：Gradle 7.3.3、Java 11。

可能原因分析 #

这不是Gradle或Kapt的普遍已知Bug，大概率是GitHub Actions Ubuntu runner的环境特性或构建配置细节导致的：

• 大小写敏感差异：Linux（Ubuntu）文件系统是大小写敏感的，而MacOS默认是大小写不敏感的。如果代码里引用生成类的包名、类名大小写和实际生成的文件不一致，本地Mac能正常识别，但Ubuntu runner会直接报错找不到。
• Kapt任务未按时执行：GitHub Actions中可能因为缓存复用或任务依赖缺失，导致生成Kapt类的任务没在编译任务之前执行，编译阶段自然找不到生成的类。
• 缓存冲突：GitHub Actions的Gradle缓存可能留存了旧的构建产物，新生成的类没被正确写入或读取。

解决方案 #

1. 检查大小写一致性 #

仔细核对代码中import语句的包名、类名大小写，和Kapt实际生成的文件路径、文件名完全匹配。比如生成的文件是MyGeneratedClass.java，就不能写成myGeneratedClass或者MygeneratedClass。

2. 强制绑定Kapt与编译任务的依赖关系 #

在模块的build.gradle中添加配置，确保编译任务必须等Kapt生成类的任务完成后再执行：

android {
    // 保持原有compileOptions和kotlinOptions配置
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_11
        targetCompatibility JavaVersion.VERSION_11
    }
    kotlinOptions {
        jvmTarget = "11"
    }
}

// 确保Java编译任务依赖Kapt的stub生成和kapt核心任务
tasks.withType(JavaCompile) {
    dependsOn tasks.withType(org.jetbrains.kotlin.gradle.tasks.KaptGenerateStubsTask)
    dependsOn tasks.withType(org.jetbrains.kotlin.gradle.tasks.KaptTask)
}

3. 清理GitHub Actions的Gradle缓存 #

在你的GitHub Actions workflow文件中，添加清理步骤，避免旧缓存干扰：

- name: 清理Gradle构建产物
  run: ./gradlew clean

或者调整缓存key，让它包含Kapt相关配置的哈希值，确保缓存能正确更新：

- name: 缓存Gradle依赖
  uses: actions/cache@v3
  with:
    path: |
      ~/.gradle/caches
      ~/.gradle/wrapper
    key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle*', '**/gradle-wrapper.properties', '**/kapt/**/*.kt') }}
    restore-keys: |
      ${{ runner.os }}-gradle-

4. 显式指定Kapt生成路径 #

在build.gradle中明确配置Kapt的生成路径，避免不同环境下的路径解析差异：

kapt {
    generateStubs = true
    arguments {
        arg("kapt.kotlin.generated", "${project.buildDir}/generated/source/kapt")
    }
}

总结 #

优先排查大小写问题，这是跨MacOS和Linux环境最常见的坑；其次调整任务依赖和缓存策略，确保Kapt任务在编译前完成。如果以上方法都无效，可以尝试升级Gradle到7.4及以上版本（仍兼容Java11），看是否能解决潜在的任务调度问题。

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