第4章 使用 Version Catalog 统一管理 Compose Compiler 版本

4.1 原理：为何需要 Version Catalog

在大型 Android 项目中，Compose Compiler 版本通常在多个模块的 build.gradle.kts 中重复声明。一旦版本升级或降级，需逐一修改，极易引发不一致。Gradle 7.0+ 引入的 Version Catalog（版本目录）机制，通过集中式 libs.versions.toml 文件管理所有依赖版本号与库坐标，实现“一处定义，全局引用”。

核心原理：类型安全的访问器（Type-safe Accessors）。Gradle 根据 TOML 文件自动生成扩展函数，开发者可在模块脚本中直接引用 libs.compose.compiler 等属性，编译期即保证版本一致性。

4.2 实现流程：三步完成统一管理

1. 创建 gradle/libs.versions.toml – 定义版本号、库声明和插件声明。
2. 在各模块 build.gradle.kts 中引用 – 使用 Kotlin 类型安全访问器或 libs.* 语法。
3. Gradle 同步 – 同步后版本生效，可在项目视图中验证。

4.3 配置示例：libs.versions.toml

以下为完整的 TOML 配置，涵盖 Compose 核心依赖及 Compiler 版本：

[versions]
compose-bom = "2024.10.01"
compose-compiler = "1.5.15"
kotlin = "1.9.24"
agp = "8.7.3"

[libraries]
compose-bom = { group = "androidx.compose", name = "compose-bom", version.ref = "compose-bom" }
compose-ui = { group = "androidx.compose.ui", name = "ui" }
compose-material3 = { group = "androidx.compose.material3", name = "material3" }
compose-compiler = { module = "androidx.compose.compiler:compiler", version.ref = "compose-compiler" }

[plugins]
android-application = { id = "com.android.application", version.ref = "agp" }
kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }

4.4 依赖声明：模块中的引用方式

在模块的 build.gradle.kts 中：

plugins {
    alias(libs.plugins.android.application)
    alias(libs.plugins.kotlin.android)
}

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

dependencies {
    implementation(platform(libs.compose.bom))
    implementation(libs.compose.ui)
    implementation(libs.compose.material3)
}

注意 kotlinCompilerExtensionVersion 不再写死，而是通过 libs.versions.compose.compiler.get() 动态读取 TOML 中的版本值。

4.5 调试与验证

• 检查生成访问器：同步后在 Build Output 中可看到 Accessors from libs.versions.toml 提示。
• 查看最终版本：执行 ./gradlew :app:dependencies --configuration debugRuntimeClasspath 确认 compose-compiler 版本一致。
• IDE 提示：Kotlin DSL 版本过低时可能无法识别 libs.*，需升级 Gradle 及 Kotlin 插件。

4.6 部署与团队协作

将 gradle/libs.versions.toml 纳入版本控制，CI 流程中通过 --refresh-dependencies 强制同步。推荐搭配 Renovate 或 Dependabot 自动提交版本更新 PR，专人审查后合并。

4.7 常见错误与避坑

4.8 性能与稳定性优化

• 减少 Gradle 构建扫描次数：统一版本后，模块间依赖冲突概率降低，增量编译更稳定。
• 利用 BOM 进一步简化：对于 Compose UI 系列库，使用 compose-bom 即可，不必为每个 artifact 单独声明版本。
• 结合 kotlinCompilerExtensionVersion 版本校验：可在 CI 脚本中增加断言，确保 Compiler 版本与 Kotlin 版本在官方支持列表中。