📚 课程目录第1章理解版本兼容核心概念

1. 理解版本兼容核心概念

Compose Compiler 是 Kotlin 编译器的特殊插件，负责将 @Composable 函数、remember、LaunchedEffect 等声明式 API 转换为底层字节码。Kotlin 编译器（kotlinc）的每个次要版本（例如 1.5 → 1.6 → 1.7）都会引入新的内部 IR 和 AST 结构，迫使 Compose Compiler 必须用匹配的坐标重新编译，否则产生不可预测的链接或运行时错误。

为什么必须精确匹配

Kotlin 官方在 Release 说明中明确：Compose Compiler 与 Kotlin 编译器之间没有向后兼容性。使用 kotlin 1.6.10 搭配 compose-compiler 1.1.1 可以正常工作，但将 compiler 升级到 1.2.0 哪怕 Kotlin 主版本不变也会导致编译崩溃。

常见陷阱： 尝试使用“接近”版本（如 kotlin 1.5.31 + compose-compiler 1.0.4）可能在 IDE 中通过语法检查，但构建时会产生 Unsupported Kotlin version 异常；生产环境务必查阅官方兼容矩阵。

版本映射表示例（2022‑2024 区间）

Kotlin 版本	Compose Compiler	Jetpack Compose BOM	备注
1.5.31	1.0.5	2021.10.01	早期稳定版
1.6.10	1.1.1	2022.02.00	支持 `@Stable` 改进
1.7.10	1.2.0	2022.10.00	引入实验性性能优化
1.8.10	1.3.2	2023.04.00	默认启用 `@NonRestartableComposable`
1.9.22	1.5.10	2024.01.00	K2 编译器过渡期

  匹配检查脚本： 在 Gradle 构建中可以通过 kotlinCompilerVersion 与 composeOptions.kotlinCompilerExtensionVersion 对比；若不一致，构建系统会打印警告。

官方兼容性矩阵

Jetpack Compose 团队在 Android Developers 站点维护动态兼容表（禁止使用网络图片，此处仅描述矩阵结构）。矩阵以 Kotlin 版本为行、Compose Compiler 版本为列，绿色单元格表示官方验证的稳定组合，黄色表示可能工作但未完全测试，红色表示已知不兼容。下表为抽象示例：

Kotlin \ Compiler	1.0.5	1.1.1	1.2.0	1.3.2
1.5.31	✔	✘	✘	✘
1.6.10	✘	✔	⚠	✘
1.7.10	✘	✘	✔	⚠
1.8.10	✘	✘	✘	✔

上表中 ✔ 表示官方推荐、⚠ 表示需自行验证、✘ 表示编译期即报错。实际矩阵与时间轴强相关，每次 Kotlin 发布后约 1～2 周会更新 Compose Compiler 对应版本。

构建配置中的版本声明

在 build.gradle.kts（模块级）中，应同时声明 Kotlin 和 Compose Compiler 版本：

// 模块级 build.gradle.kts
android {
    composeOptions {
        kotlinCompilerExtensionVersion = "1.5.10"   // 必须与 kotlin 版本匹配
    }
}
kotlin {
    kotlinVersion = "1.9.22"
}

若使用 compose‑compiler‑gradle‑plugin 方式，可以省略 composeOptions 并直接通过 org.jetbrains.compose 插件管理版本，但核心匹配原则不变。

诊断技巧： 在终端执行 ./gradlew buildEnvironment | grep compose 查看依赖树，若发现多个不同 compiler 版本，说明存在传递依赖冲突，需在 resolutionStrategy 中显式统一。

Compose Compiler 与 Kotlin 编译器关系图

下图展示了从源代码到字节码的流水线，其中 Compose Compiler 插件紧耦合于特定 Kotlin 编译器的内部 IR 传递。

图中虚线表示经过 Compose Compiler 插件处理后的 IR 变换回路，实线表示版本匹配检查直接作用于插件版本声明。任何一侧版本不匹配都可能导致编译流水线断裂。

核心结论

Compose Compiler 是 Kotlin 编译器的定制插件，无独立分发；必须与 kotlinc 的次要版本一致。
官方兼容矩阵是唯一可信源，第三方网站可能过时；构建时建议使用 constraints 强制统一版本。
从 Kotlin 2.x（K2 编译器）开始，Compose Compiler 内部重构为 compose‑compiler‑kotlin‑2，映射规则将再次调整。