# 排除 Kotlin 2 导致的 Android 构建失败

> 在构建 Kotlin 版本低于 2.0.0 的原生 Android app 时，识别和修复由 LevelPlay 9.6.0 中引入的 Kotlin 2 依赖项引起的 Android 构建失败。

如果使用低于 2.0.0 的 Kotlin 版本，可能会遇到 Android 构建失败。本指南介绍如何识别和解决这些问题。

## 症状##symptom

将 LevelPlay SDK 依赖项项升级到 9.6.0 后，Android 构建 Kotlin 编译期间会失败。Android Studio 中的构建输出面板将失败的任务显示为`:app:compile<Variant>Kotlin`（例如`:app:compileDebugKotlin`），Gradle 日志包含类似于以下内容的节选：

```xml
> 任务：app:compileDebugKotlin FAILED
  e：在依赖关系中找到不兼容的类。将它们从
  类路径或使用“-Xskip-metadata-version-check”抑制错误
  e: file:///.../transformed/jetified-kotlin-stdlib-2.1.21.jar!/META-INF/kotlin-stdlib.kotlin_module
  模块是使用不兼容的 Kotlin 版本编译的。二进制文件
  其元数据的版本为 2.1.0，预期版本为 1.8.0。
  e：文件:///.../src/main/java/.../<YourFile>.kt:NN:NN 类“kotlin.Unit”为
  使用不兼容的 Kotlin 版本进行编译。实际元数据
  版本为 2.1.0，但编译器版本 1.8.0 可以读取版本
  到 1.9.0。
```

要在应用修复之前进行确认，可以检查已解析的 Kotlin stdlib 版本：

```kotlin
./gradlew :app:dependencies | grep kotlin-stdlib
```

如果在项目的 Kotlin Gradle 插件处于 1.x 时在图表中看到`kotlin-stdlib:2.x.x`，本指南适用于您。

## 原因##causes

Android 构建失败可能出于以下原因：

* LevelPlay SDK 9.6.0（及其某些网络适配器）对 Kotlin 2.x 标准库（目前为 `kotlin-stdlib-2.1.21`）有依赖项。
* 为项目定义的 Kotlin 版本低于 2.0 将与使用 Kotlin 2.x 的 LevelPlay SDK 9.6.0 不兼容。

## 解决方案##resolution

要解决此问题，请将项目使用的 Kotlin Gradle Plugin (KGP) 版本升级到 2.0.0 或更高版本。建议目标为 2.1.21，即 LevelPlay 9.6.0 版本本身，因此项目的 stdlib 与 SDK 的 stdlib 匹配。

### 升级要求##upgrade-requirements

升级到 Kotlin 2.0 或更高版本可能需要更新或配置相关的工具链版本，如下所示：

* 运行 Kotlin 2.0 或更高版本编译器需要 JDK 17。要在 Android Studio 中设置 JDK 17，请在项目中转到 **设置** > **构建、执行、部署** > **构建工具** > **Gradle** > **Gradle JDK**。
* KSP（如果使用）与 Kotlin 版本绑定。将 `com.google.devtools.ksp` 升级到与您的 Kotlin 版本匹配的版本。
* Jetpack Compose（如果使用）需要从 Kotlin 2.0 开始的 Compose 编译器 Gradle 插件。旧版`composeOptions.kotlinCompilerExtensionVersion`设置不再适用。
* 升级 Kotlin 也可能会在 K2 编译器下您自己的代码中显示弃用警告或`source-incompatible`更改。请参阅 [Kotlin 2.0.0 新增发布说明](https://kotlinlang.org/docs/whatsnew20.html)以了解更多信息。

## 验证分辨率##verify-the-resolution

1. 在 Android Studio 中，运行**文件** > **Sync Project with Gradle Files**，**构建** > **重新构建项目**。
2. 通过检查确认构建已修复：
   a.Gradle 输出以`BUILD SUCCESSFUL`消息结束，`:app:compile<Variant>Kotlin`完成时没有错误。
   b.在依赖关系消息中找到的不兼容类不再出现在构建日志中。

如果报错仍然存在，请尝试以下操作：

* 使用更新的 Kotlin 版本确认`build.gradle`中的 Kotlin 依赖关系。
* 先运行 `./gradlew --stop`，然后运行 `rm -rf ~/.gradle/caches/transforms-3/`，然后重新构建，从而清除 Gradle 缓存。或者，在 Android Studio 中，使用**文件** > **Invalidate Caches…**，然后重新构建。