Kotlin开发者必看：Kapt实战避坑指南（Dagger/Room配置全解析）

Kotlin开发者必看：Kapt实战避坑指南（Dagger/Room配置全解析）

如果你是一位Android开发者，并且项目已经全面转向Kotlin，那么你大概率已经和Kapt打过交道，甚至可能被它“折磨”过。在构建现代Android应用时，Dagger用于依赖注入，Room用于数据库操作，几乎成了标配。但当你信心满满地将它们集成到Kotlin项目中，却在Gradle同步或编译时遭遇各种红色错误，那种感觉确实令人沮丧。

这篇文章不是一篇泛泛而谈的Kapt科普，而是直接从实战出发，聚焦于Dagger和Room这两个最高频、也最容易出问题的库。我会结合自己踩过的坑和项目中的实际配置，为你梳理出一套从环境搭建到疑难杂症解决的完整指南。我们的目标很明确：让你能快速、稳定地在Kotlin项目中配置好这些工具，把精力真正花在业务逻辑上，而不是和构建脚本纠缠不清。

1. 环境搭建与基础配置：奠定稳固基石

在开始任何具体的库配置之前，一个清晰、正确的项目基础环境是避免后续无数麻烦的前提。很多配置问题，根源在于Gradle插件版本、Kotlin版本以及编译选项之间的不匹配。

1.1 项目级Gradle配置：版本对齐是关键

打开你的项目根目录下的 build.gradle.kts（或 build.gradle），这里的配置为所有模块定下了基调。我强烈建议使用Kotlin DSL（*.kts），它在类型安全和代码提示方面更有优势。

// 项目根目录 build.gradle.kts
buildscript {
    // 定义版本变量，确保全局一致
    extra.apply {
        set("kotlinVersion", "1.9.22")
        set("daggerVersion", "2.48")
        set("roomVersion", "2.6.1")
    }

    repositories {
        google()
        mavenCentral()
    }
    dependencies {
        // 使用定义好的版本变量
        classpath("com.android.tools.build:gradle:8.2.0")
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:${extra["kotlinVersion"]}")
    }
}

注意：版本号是动态变化的，本文使用的版本在撰写时是稳定的组合。在实际项目中，你应该定期查看各库的官方发布页，但升级时务必注意版本间的兼容性，尤其是大版本升级。

一个常见的陷阱是Android Gradle插件（AGP）版本与Kotlin编译器版本不兼容。你可以参考以下兼容性对照表，这是一个经验性的参考，能帮你避开大部分初始问题：

1.2 模块级Gradle配置：启用Kapt与基础依赖

进入你的应用或库模块的 build.gradle.kts 文件。第一步是正确应用插件。插件的应用顺序有时会产生影响，一个稳妥的顺序是：

// 模块级 build.gradle.kts
plugins {
    id("com.android.application") // 或 id("com.android.library")
    id("org.jetbrains.kotlin.android")
    // kotlin-kapt 插件必须在 kotlin-android 之后应用
    id("org.jetbrains.kotlin.kapt")
}

接下来，在 android 块中，确保你已经为Kotlin配置了正确的编译选项。这对于Kapt处理注解至关重要：

android {
    compileSdk = 34

    defaultConfig {
        applicationId = "com.yourcompany.yourapp"
        minSdk = 24
        targetSdk = 34
        // ... 其他配置
    }

    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }
    kotl