Android 消费者 SDK 3.0 迁移指南
使用集合让一切井井有条
根据您的偏好保存内容并对其进行分类。
迁移到 Kotlin 2.0
如果您使用的是 Consumer SDK for Android 3.0 及更高版本,则必须升级到 Kotlin 2.0。本页提供了相关指南,可帮助您轻松过渡到新的 Kotlin 版本。
Gradle 和 AGP 兼容性
Kotlin 2.0 对 Gradle 和 Android Gradle 插件 (AGP) 版本的最低版本和最高版本有要求。确保您的项目满足 Kotlin 2.0 的这些要求。
Consumer SDK 3.0 及更高版本的 AGP 最低版本
Consumer SDK 3.0 需要使用 AGP 7.3 及更高版本。
完整 R8 模式
消费者 SDK v3 及更低版本不支持 Full R8 模式。如果您的应用以 AGP 8.0 及更高版本为目标平台,则必须明确停用完整 R8 模式。
# settings.gradle
android.enableR8.fullMode=false
Kotlin 版本兼容性
Kotlin 支持向后兼容之前三个语言版本。这意味着,如果您已将 Kotlin 1.7 及更高版本与 Consumer SDK 搭配使用,则应该能够升级到 Kotlin 2.0,而无需解决所有重大变更。不过,Kotlin 兼容性仅适用于稳定的语言功能。如果您在 Kotlin 语言中使用的是 Alpha 版、Beta 版或实验性功能,那么在升级时可能需要进行其他更改。
Kotlin 兼容性标志
如上一部分所述,升级时,Kotlin 最多支持该语言的 3 个先前版本。Kotlin 提供了两个标志来帮助限制重大变更:
language-version X.Y
此标志可将行为方面的重大变更还原为之前的 Kotlin 版本。例如,如果您使用的是 Kotlin 1.7,则可以指定 [ -
language-version 1.7]
,这样新的重大变更将不再生效:
android {
kotlinOptions {
languageVersion = '1.7'
}
}
api-version X.Y
此标志可防止在依赖的下游代码准备好纳入 Kotlin 2.0 之前使用新的 API。
android {
kotlinOptions {
apiVersion = '1.7'
}
}
更具针对性的方法
除了使用 Kotlin 兼容性标志之外,我们还建议您查看 Kotlin 版本说明,并选择要从升级前的版本中保留的行为。Kotlin 在每个版本的兼容性指南中提供了一份重大变更列表,以及可用于保留原始行为的标志:
如未另行说明,那么本页面中的内容已根据知识共享署名 4.0 许可获得了许可,并且代码示例已根据 Apache 2.0 许可获得了许可。有关详情,请参阅 Google 开发者网站政策。Java 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC):2025-08-31。
[null,null,["最后更新时间 (UTC):2025-08-31。"],[[["\u003cp\u003eUpgrading to Kotlin 2.0 is mandatory when utilizing the Consumer SDK for Android 3.0 or later.\u003c/p\u003e\n"],["\u003cp\u003eEnsure your Gradle and Android Gradle Plugin (AGP) versions meet the compatibility requirements for Kotlin 2.0, with Consumer SDK 3.0+ necessitating AGP 7.3 or higher.\u003c/p\u003e\n"],["\u003cp\u003eDisable Full R8 mode explicitly for Consumer SDK v3 and below when targeting AGP 8.0+.\u003c/p\u003e\n"],["\u003cp\u003eWhile Kotlin generally offers backward compatibility, potential breaking changes might require adjustments, especially when using alpha, beta, or experimental Kotlin features.\u003c/p\u003e\n"],["\u003cp\u003eLeverage Kotlin compatibility flags like \u003ccode\u003elanguage-version\u003c/code\u003e and \u003ccode\u003eapi-version\u003c/code\u003e or consult the Kotlin compatibility guides for managing specific breaking changes during the upgrade.\u003c/p\u003e\n"]]],["To migrate to Kotlin 2.0 with Consumer SDK 3.0+, ensure your Gradle and AGP versions meet Kotlin 2.0 requirements (AGP 7.3+). Disable Full R8 mode if using AGP 8.0+ by setting `android.enableR8.fullMode=false` in `settings.gradle`. Utilize Kotlin compatibility flags, `languageVersion` and `apiVersion`, to revert breaking changes or limit new API usage. Consult the Kotlin compatibility guides for specific version changes and behavior flags.\n"],null,["Migrate to Kotlin 2.0\n\nIf you are using the Consumer SDK for Android 3.0+ you must upgrade to Kotlin\n2.0. This page provides guidance to ease the transition to the new Kotlin\nversion.\n| **Note:** For information on upgrading to Kotlin 1.9, which was required for the Consumer SDK 5.0+ see the [Kotlin 1.9 upgrade\n| guide](/maps/documentation/transportation-logistics/on-demand-rides-deliveries-solution/trip-order-progress/migrations/android_consumer_sdk_v2.0_migration#kotlin_16_to_19_migration).\n\nGradle and AGP compatibility\n\nKotlin 2.0 has [requirements for the minimum and maximum\nversions](https://kotlinlang.org/docs/gradle-configure-project.html#apply-the-plugin)\nfor your Gradle and Android Gradle Plugin (AGP) version. Ensure that your\nproject meets these requirements for Kotlin 2.0.\n\nAGP minimum version for the Consumer SDK 3.0+\n\nConsumer SDK 3.0 requires using AGP 7.3+.\n\nFull R8 mode\n\nConsumer SDK v3 and below does not support Full R8 mode. You must explicitly\ndisable Full R8 mode if your application targets AGP 8.0+. \n\n # settings.gradle\n android.enableR8.fullMode=false\n\nKotlin version compatibility\n\nKotlin supports backwards compatibility with [three previous language\nversions](https://kotlinlang.org/docs/kotlin-evolution-principles.html#compatibility-options).\nThis means that if you are already using Kotlin 1.7+ with the Consumer SDK, you\nshould be able to upgrade to Kotlin 2.0 without having to resolve all of the\nbreaking changes. However, [Kotlin compatibility only applies to stable language\nfeatures](https://kotlinlang.org/docs/components-stability.html#stability-levels-explained).\nIf you are using alpha, beta or experimental features in the Kotlin language,\nthen you may have to make additional changes when upgrading.\n\nKotlin compatibility flags\n\nAs noted in the previous section, Kotlin supports up to 3 previous versions of\nthe language when upgrading. Kotlin [supplies two flags to help with limiting\nbreaking changes](https://kotlinlang.org/docs/compatibility-modes.html):\n\nlanguage-version X.Y\n\nThis flag reverts breaking changes to the behavior of a previous Kotlin version.\nFor example, if you are using Kotlin 1.7, you could specify `[ -\nlanguage-version 1.7]` and the new breaking changes would no longer take effect: \n\n android {\n kotlinOptions {\n languageVersion = '1.7'\n }\n }\n\napi-version X.Y\n\nThis flag prevents new APIs from being used before dependent downstream code is\nready to incorporate Kotlin 2.0. \n\n android {\n kotlinOptions {\n apiVersion = '1.7'\n }\n }\n\nA more targeted approach\n\nIn addition to using Kotlin compatibility flags, we recommend reviewing the\nKotlin release notes and choosing the behaviors that you would like to retain\nfrom the version that you are upgrading from. Kotlin provides a list of breaking\nchanges and the flags that can be set to retain the original behavior in its\ncompatibility guides for each version:\n\n- [1.8 compatibility guide](https://kotlinlang.org/docs/compatibility-guide-18.html)\n- [1.9 compatibility guide](https://kotlinlang.org/docs/compatibility-guide-19.html)\n- [2.0 compatibility guide](https://kotlinlang.org/docs/compatibility-guide-20.html)"]]