📚 课程目录第2章搭建兼容开发环境

2. 搭建兼容开发环境：检查当前Kotlin版本、安装对应Compose Compiler插件、配置IDE提示

在开始使用Compose Multiplatform或Jetpack Compose之前，必须确保Kotlin编译器与Compose Compiler版本匹配。版本错配会导致编译失败、运行时崩溃或IDE报红。本章将引导你完成环境搭建的完整流程：从检查当前Kotlin版本，到选择正确的Compose Compiler插件，再到配置IDE以消除误报。

2.1 检查当前Kotlin版本

Kotlin版本由项目级build.gradle.kts（或build.gradle）中的kotlin插件版本决定。可使用以下两种方式确认当前版本。

2.1.1 通过Gradle文件检查

打开项目根目录的build.gradle.kts，查找类似配置：

plugins {
    kotlin("jvm") version "1.9.22" apply false
    // 或 kotlin("android") version "1.9.22" apply false
}

其中1.9.22即为当前Kotlin版本。如果使用Gradle Kotlin DSL，版本号也可能出现在libs.versions.toml的版本目录中。

2.1.2 通过命令行检查

在终端中执行以下命令，可查看全局安装的Kotlin编译器版本（注意项目级别以Gradle指定的为准）：

kotlin -version

或使用Gradle任务查看项目实际使用的Kotlin版本：

./gradlew kotlinDslAccessorsReport --quiet | grep "kotlin"
# 更推荐直接查看 build.gradle.kts

💡 提示：Android Studio用户可以在File → Project Structure → Project中查看Kotlin版本。但Gradle文件是权威来源——IDE显示可能滞后于脚本。

2.2 安装对应Compose Compiler插件

Compose Compiler是一个Kotlin编译器插件，它必须在Gradle构建脚本中显式声明。关键约束：Compose Compiler版本必须与Kotlin版本严格一一对应。下表列出常见兼容组合（以2024年稳定趋势为例）：

Kotlin 版本	Compose Compiler 版本	说明
1.9.22	1.5.10	Jetpack Compose 推荐基线
1.9.23	1.5.11	小版本补丁修复
1.9.24	1.5.14	兼容性增强
2.0.0+	2.0.0+	Compose Multiplatform 需同步升级

在模块级build.gradle.kts中，通过kotlinCompilerExtensionVersion属性指定Compose Compiler版本。示例：

android {
    composeOptions {
        kotlinCompilerExtensionVersion = "1.5.10"  // 对应Kotlin 1.9.22
    }
}

若使用Compose Multiplatform（非Android），则在公共模块build.gradle.kts中添加插件声明：

plugins {
    kotlin("multiplatform") version "1.9.22"
    id("org.jetbrains.compose") version "1.6.0"  // 包含对应Compose Compiler
}

此时org.jetbrains.compose插件会自动匹配兼容的Compose Compiler版本，无需手动设置kotlinCompilerExtensionVersion。

⚠️ 常见错误：如果将Kotlin从1.9.22升级到1.9.23，但忘记更新kotlinCompilerExtensionVersion为1.5.11，Gradle同步时会报错：This version (1.5.10) of the Compose Compiler requires Kotlin version 1.9.22 but you are using Kotlin 1.9.23。务必逐版本匹配。

2.3 配置IDE提示与预览支持

即使Gradle构建成功，IDE也可能显示红色波浪线或无法运行@Preview。这通常是因为IDE的Kotlin插件和Compose插件未同步。按以下步骤配置。

2.3.1 确保IDE Kotlin插件版本匹配

Android Studio / IntelliJ IDEA的Kotlin插件版本与项目使用的Kotlin版本应保持一致。检查路径：Settings → Languages & Frameworks → Kotlin。如果插件版本低于或高于项目版本，IDE可能无法正确解析Compose编译器生成的代码。

2.3.2 启用Compose预览

在Settings → Editor → Inlay Hints → Kotlin中，勾选Show composable function previews。同时确保模块的build.gradle.kts中已启用compose特性：

android {
    buildFeatures {
        compose = true
    }
}

2.3.3 清理缓存并重建

如果IDE报红但Gradle编译通过，可尝试：File → Invalidate Caches / Restart → Invalidate and Restart。这能清除Compose编译器插件缓存，使IDE重新解析。

    📌 验证清单：
    运行 ./gradlew compileDebugKotlin 无错误
IDE中 @Preview 注解能渲染组件预览图
修改Compose代码后，Gradle task "compile...Kotlin" 无版本冲突警告

2.4 版本匹配决策流程

下图从“检查Kotlin版本”到“验证编译成功”的完整决策路径，帮助你快速定位并修复版本不兼容问题。

以上流程图中，如果同步或编译失败，沿虚线箭头进入“版本不匹配”分支，此时应参考第3章（版本映射表工具）自动修正，或手动调整Kotlin/Compose Compiler版本至兼容组合。

2.5 常见问题与解决

问题症状	可能原因	解决方案
Gradle sync 报错 “Compose compiler version … requires Kotlin …”	kotlinCompilerExtensionVersion 与 Kotlin 版本不匹配	查阅兼容表，更新 `kotlinCompilerExtensionVersion`
IDE 中 @Preview 显示 “Preview not available”	IDE Kotlin 插件版本过旧，或未启用预览功能	更新 Kotlin 插件至项目版本；勾选预览 inlay hints
编译成功但 IDE 报红线（误报）	编译器缓存或IDE索引损坏	Invalidate Caches & Restart
Compose Multiplatform 项目找不到 org.jetbrains.compose 插件	未在 settings.gradle.kts 中添加插件仓库	添加 `mavenCentral()` 或 `google()` 仓库