第3章 单模块项目适配流程：修改build.gradle、同步、编译验证

3.1 适配原理与版本对应关系

单模块项目是Android开发中最常见的工程结构。当项目中引入Jetpack Compose后，org.jetbrains.kotlin:kotlin-compiler-embeddable（Kotlin编译器）与androidx.compose.compiler:compiler（Compose编译器扩展）必须严格对齐版本。每个Kotlin发行版对应一组经过测试的Compose Compiler版本，若版本不匹配，Gradle同步或编译时会抛出类似Kotlin compiler version mismatch或Unsupported Kotlin version的错误。

适配流程的核心操作是修改build.gradle（项目级和app模块级），更新kotlin_version与Compose Compiler的版本号，然后触发Gradle同步并执行编译验证。

3.2 实现流程

1. 确认项目中使用的Kotlin版本（根build.gradle中的ext.kotlin_version）。
2. 根据版本对应表选择兼容的Compose Compiler版本。
3. 修改app模块build.gradle中的composeOptions.kotlinCompilerExtensionVersion。
4. 同步Gradle（命令行或IDE按钮）。
5. 执行编译验证（assembleDebug或IDE构建）。
6. 根据错误信息调整版本，重复同步与编译直至成功。

3.3 修改 build.gradle

根项目 build.gradle（Project级别）：声明Kotlin版本变量（若已存在则核对）。

buildscript {
    ext.kotlin_version = '1.9.24'   // 指定Kotlin版本
    repositories {
        google()
        mavenCentral()
    }
    dependencies {
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
    }
}

app模块 build.gradle（Module级别）：添加Compose配置，并正确设置kotlinCompilerExtensionVersion。

android {
    compileSdk 34
    defaultConfig {
        minSdk 24
        targetSdk 34
    }

    buildFeatures {
        compose true
    }

    composeOptions {
        kotlinCompilerExtensionVersion = '1.5.14'  // 与Kotlin 1.9.24匹配
    }
}

dependencies {
    implementation 'androidx.compose.ui:ui:1.6.7'
    implementation 'androidx.compose.material3:material3:1.2.1'
    implementation 'androidx.compose.compiler:compiler:1.5.14'
    // 其他依赖...
}

3.4 同步Gradle

在终端（项目根目录）执行同步命令：

./gradlew --stop
./gradlew clean
./gradlew sync

或在Android Studio中点击工具栏的“Sync Project with Gradle Files”按钮（大象图标）。 同步成功后，IDE会显示BUILD SUCCESSFUL且无版本错误。

3.5 编译验证

同步通过后，编译完整的Debug APK以验证所有Kotlin与Compose代码能正常生成字节码：

./gradlew assembleDebug

若编译输出以BUILD SUCCESSFUL结尾，且控制台无红色错误信息，则适配完成。

3.6 常见错误及处理

3.7 适配流程结构图

下图概括了单模块项目从Kotlin版本检查到编译验证的完整适配流程：

3.8 验证成功后的稳定性说明

编译通过后，建议运行./gradlew lint和单元测试（若有）确保无兼容性问题。若项目中还使用了Compose BOM，需同步更新androidx.compose:compose-bom:2024.10.00等版本，保持所有Compose库版本一致。