Kotlin 版本相容性和遷移

本頁說明 Navigation SDK 的 Kotlin 版本相容性,並提供遷移至新版本的指南。

下表列出近期 Navigation SDK 版本的 Kotlin 版本需求,以及建議的 AGP 和 Gradle 版本。

Navigation SDK 版本 Kotlin 版本 (必要) Android Gradle 外掛程式 (AGP) 和 Gradle 版本 (建議)
8.0+ 2.3.0
  • AGP 9.0.1
  • Gradle 9.1.0

重要事項:如果是 Navigation SDK 8.0 以上版本,AGP 9.0.1 是最低需求,而非建議版本。SDK 會宣告 minAndroidGradlePluginVersion=9.0.1,且使用舊版 AGP 建構作業會失敗。

7.7 - 7.9 2.3.0
  • AGP 8.13.2
  • Gradle 8.13
7.3 - 7.6 2.2.10
  • AGP 8.10.0
  • Gradle 8.11.1
6.3 - 7.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.3 回溯相容於 Kotlin 2.2。也就是說,如果您已搭配使用 Kotlin 2.2 和 Navigation SDK,應該可以升級至 Kotlin 2.3,不必解決所有破壞性變更。不過,這僅適用於穩定的語言功能。如果您在 Kotlin 語言中使用 Alpha 版、Beta 版或實驗功能,則可能需要在升級時進行額外變更。

順利過渡:Kotlin 相容性旗標

Kotlin 提供兩個標記,有助於限制破壞性變更:https://kotlinlang.org/docs/compatibility-modes.html

language-version X.Y

這個旗標會將破壞性變更還原為先前 Kotlin 版本的行為。舉例來說,如果您使用 Kotlin 2.2,可以指定 [ - language-version 2.2],新的破壞性變更就不會生效:

android {
   kotlinOptions {
       languageVersion = '2.2'
   }
}

api-version X.Y

如果使用的 API 來自比 apiVersion 新的 Kotlin 版本,這個旗標會擲回 Gradle 建構錯誤。

android {
   kotlinOptions {
       apiVersion = '2.2'
   }
}

更精準的做法

除了使用 Kotlin 相容性旗標外,建議您查看 Kotlin 版本資訊,並從要升級的版本中選擇要保留的行為。Kotlin 在各版本的相容性指南中,列出破壞性變更和可設定的旗標,以便保留原始行為:

日後的 Kotlin 升級

Kotlin 每 6 個月會發布新版本 (即語言版本),而 Google 通常會在 1 到 2 個月後,將最新版本納入產品預設版本。先前的 Kotlin 版本包含破壞性變更,因此 Navigation SDK 客戶必須升級至新版本。因此,建議您在採用最新版 Navigation SDK 時,每 6 個月升級一次 Kotlin。