Kotlin 版本兼容性和迁移

本页提供了有关 Navigation SDK 的 Kotlin 版本兼容性的信息，以及有关迁移到较新版本的指南。

下表列出了 Kotlin 版本要求以及适用于最新版 Navigation SDK 的推荐 AGP 和 Gradle 版本。

Navigation SDK 版本 Kotlin 版本（必需） Android Gradle 插件 (AGP) 和 Gradle 版本（推荐）
6.2+ 2.1
  • AGP 8.7.3
  • Gradle 8.10.2
6.0 - 6.2 2.0
  • AGP 8.3.0
  • Gradle 8.4
5.1 - 5.99.1 1.9 我们建议使用 AGP 7.3 及更高版本，该版本针对 JDK-8272564 提供了解决方法。

Kotlin 版本兼容性

Kotlin 2.1 支持与 Kotlin 2.0 的向后兼容性。这意味着，如果您已将 Kotlin 2.0 与 Navigation SDK 搭配使用，则应该能够升级到 Kotlin 2.1，而无需解决所有重大变更。不过，这仅适用于稳定的语言功能。 如果您在 Kotlin 语言中使用的是 Alpha 版、Beta 版或实验性功能，那么在升级时可能需要进行其他更改。

简化过渡：Kotlin 兼容性标志

Kotlin 提供了两个标志来帮助限制重大变更： https://kotlinlang.org/docs/compatibility-modes.html

language-version X.Y

此标志可将行为方面的重大变更还原为之前的 Kotlin 版本。例如，如果您使用的是 Kotlin 2.0，则可以指定 [ - language-version 2.0]，这样新的重大变更将不再生效：

android {
   kotlinOptions {
       languageVersion = '2.0'
   }
}

api-version X.Y

如果使用了比 apiVersion 更新的 Kotlin 版本的 API，此标志会抛出 Gradle build 错误。

android {
   kotlinOptions {
       apiVersion = '2.0'
   }
}

更具针对性的方法

除了使用 Kotlin 兼容性标志之外，我们还建议您查看 Kotlin 版本说明，并选择要从升级前的版本中保留的行为。Kotlin 在每个版本的兼容性指南中提供了一份重大变更列表，以及可用于保留原始行为的标志：

未来的 Kotlin 升级

Kotlin 每 6 个月发布一个新版本（即语言版本），而 Google 通常会在 1-2 个月后将最新版本作为默认版本纳入我们的产品中。之前的 Kotlin 版本包含破坏性更改，导致 Navigation SDK 客户需要升级到较新版本。因此，我们建议您在采用最新版 Navigation SDK 时，每 6 个月规划一次 Kotlin 升级。