3. 手动配置 Compose Compiler Extension：buildscript vs plugin management、版本锁定技巧

3.1 原理：Compose Compiler Extension 的两种加载模式

Compose Compiler Gradle Plugin 作为 Kotlin Compiler 插件的包装，必须与项目使用的 Kotlin 版本严格匹配。Gradle 构建系统通过两种方式加载该插件：传统 buildscript 块和现代 plugins DSL + Version Catalog。两种模式的核心差异在于依赖声明的位置和版本管理方式，但最终都会生成相同的 Compiler Extension 配置。

3.2 实现流程：buildscript 方式

步骤 1：在项目根目录 build.gradle（或 build.gradle.kts）中添加 Compose Compiler Gradle Plugin 的 classpath 依赖。

// build.gradle (project-level)
buildscript {
    repositories {
        mavenCentral()
        google()
    }
    dependencies {
        classpath("org.jetbrains.compose:compose-gradle-plugin:1.5.10")
        // 注：1.5.10 对应 Kotlin 1.9.22
    }
}

步骤 2：在 module 层级的 build.gradle 应用插件并配置 composeOptions。

// app/build.gradle
plugins {
    id 'com.android.application'
    id 'org.jetbrains.kotlin.android'
    id 'org.jetbrains.compose'  // 应用 Compose 插件
}

android {
    compileSdk 34
    buildFeatures {
        compose true
    }
    composeOptions {
        kotlinCompilerExtensionVersion = "1.5.10"
    }
}

3.3 实现流程：plugins DSL + Version Catalog 方式

步骤 1：在 settings.gradle.kts 中配置 pluginManagement 和 Version Catalog（libs.versions.toml）。

// settings.gradle.kts
pluginManagement {
    repositories {
        mavenCentral()
        google()
        gradlePluginPortal()
    }
    plugins {
        // 可选：在此版本锁定
    }
}

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        mavenCentral()
        google()
    }
}

rootProject.name = "MyComposeApp"
include(":app")

步骤 2：在 gradle/libs.versions.toml 中定义 Compose Compiler 版本。

# gradle/libs.versions.toml
[versions]
compose-compiler = "1.5.10"
kotlin = "1.9.22"

[libraries]
# 其他依赖

[plugins]
compose-gradle-plugin = { id = "org.jetbrains.compose", version.ref = "compose-compiler" }
kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }

步骤 3：在 module 的 build.gradle.kts 中引用插件。

// app/build.gradle.kts
plugins {
    id("com.android.application")
    alias(libs.plugins.kotlin.android)
    alias(libs.plugins.compose.gradle.plugin)
}

android {
    composeOptions {
        kotlinCompilerExtensionVersion = libs.versions.compose.compiler.get()
    }
}

3.4 版本锁定技巧

手动管理版本时，以下三种锁定策略可防止无意间升级导致 Kotlin/Compose 不兼容：

dependencies {
    constraints {
        implementation("org.jetbrains.compose.compiler:compiler:1.5.10") {
            version { strictly("1.5.10") }
        }
    }
}

configurations.all {
    resolutionStrategy {
        force("org.jetbrains.compose.compiler:compiler:1.5.10")
    }
}

# libs.versions.toml
compose-compiler = "1.5.10"

3.5 调试与验证

执行以下命令确认 Compose Compiler Extension 是否被正确识别：

./gradlew :app:dependencies --configuration debugRuntimeClasspath | grep compose

期望输出中应包含类似：

+--- org.jetbrains.compose.compiler:compiler:1.5.10
+--- org.jetbrains.compose:compose-gradle-plugin:1.5.10

若版本号与预期不符，说明存在其他传递依赖覆盖了版本，需要检查 resolutionStrategy 或 strictly 是否生效。

3.6 性能与稳定性优化建议

1. 统一版本号：仅在 Version Catalog 或 ext 属性中声明一次 Compose Compiler 版本，避免模块间不一致。
2. 锁定 Kotlin 版本：同步在 Version Catalog 中声明 kotlin = "1.9.22"，确保 Kotlin 插件版本与 Compose Compiler 严格匹配。
3. 开启 Gradle 配置缓存：在 gradle.properties 添加 org.gradle.configuration-cache=true，减少重复解析。
4. 预编译插件分析：对于大型多模块项目，使用 buildSrc 或 included build 统一管理 Compose 插件和版本，避免 buildscript 块导致的重复解析开销。