v3.8 Android 工程升级

从 v3.8 开始,构建产出的 Android 工程默认支持新版本的 Android Studio(Flamingo | 2022.2.1)。由于 Android Gradle 插件的 要求,开发者需要将 JDK 升级到 17,同时升级 Android Studio 到 Flamingo 版本。

如果没有对构建生成的 Android 工程进行配置,可以直接删除 native/engine/android 目录和 build/android 目录,然后重新构建。这样不需要对工程进行一步步的修改升级。但是请注意,这一步操作是有风险的,如对接 SDK 的代码可能会被删除,请谨慎操作。

对于现有的原生 Android 工程,开发者可以参考以下步骤对工程进行升级:

第一步:备份当前工程

在升级之前,我们应该先备份当前的 native 目录,以防万一。比如可以用 Git 保存当前修改.

第二步:升级Gradle插件版本

Gradle 插件版本是 Gradle 与 Android 构建系统之间的接口。因此,在升级 Gradle 之前,我们需要先升级 Gradle 插件版本。在项目的 native/engine/android/build.gradle 文件中,将 classpath 中的 Gradle 插件版本改为 8.0.2。

  1. // jcenter() // keeped as anchor, will be removed soon
  2. }
  3. dependencies {
  4. - classpath 'com.android.tools.build:gradle:4.1.0'
  5. + classpath 'com.android.tools.build:gradle:8.0.2'
  6. // NOTE: Do not place your application dependencies here; they belong
  7. // in the individual module build.gradle files

第三步:移除 package 字段

移除 native/engine/android/app/AndroidManifest.xml 文件中的 package 属性。

  1. <?xml version="1.0" encoding="utf-8"?>
  2. <manifest xmlns:android="http://schemas.android.com/apk/res/android"
  3. - package="com.cocos.test"
  4. android:installLocation="auto">
  5. <uses-permission android:name="android.permission.INTERNET"/>

native/engine/android/app/build.gradle 中的修改 applicationId 为 namespace

  1. compileSdkVersion PROP_COMPILE_SDK_VERSION.toInteger()
  2. buildToolsVersion PROP_BUILD_TOOLS_VERSION
  3. ndkPath PROP_NDK_PATH
  4. + namespace APPLICATION_ID
  5. compileOptions {
  6. sourceCompatibility JavaVersion.VERSION_1_8
  7. @@ -17,7 +18,6 @@ android {
  8. }
  9. defaultConfig {
  10. - applicationId APPLICATION_ID
  11. minSdkVersion PROP_MIN_SDK_VERSION
  12. targetSdkVersion PROP_TARGET_SDK_VERSION
  13. versionCode 1

第四步:升级 Gradle 版本

接下来,我们需要升级 Gradle wrapper 版本。在项目的 build/android/proj/gradle/wrapper/gradle-wrapper.properties 文件中,将 distributionUrl 改为 8.0.2,如下所示:

  1. distributionUrl=https\://services.gradle.org/distributions/gradle-8.0.2-bin.zip

第五步: 更新 Proguard Rules

添加下面的内容到文件 native/engine/android/app/proguard-rules.pro

  1. # This is generated automatically by the Android Gradle plugin.
  2. -dontwarn android.hardware.BatteryState
  3. -dontwarn android.hardware.lights.Light
  4. -dontwarn android.hardware.lights.LightState$Builder
  5. -dontwarn android.hardware.lights.LightState
  6. -dontwarn android.hardware.lights.LightsManager$LightsSession
  7. -dontwarn android.hardware.lights.LightsManager
  8. -dontwarn android.hardware.lights.LightsRequest$Builder
  9. -dontwarn android.hardware.lights.LightsRequest
  10. -dontwarn android.net.ssl.SSLSockets
  11. -dontwarn android.os.VibratorManager

第六步:安装 JDK 17

官网 上下载并安装 JDK 17。安装过程中需要注意配置环境变量。

安装完成后,可以通过在命令行输入 java -version 来检查是否安装成功。

第七步:升级 Android Studio

在升级 Gradle 之后,我们还需要升级 Android Studio。如果您当前使用的是较老版本的 Android Studio,请先下载最新版本的 Android Studio(Flamingo | 2022.2.1)。下载地址为: https://developer.android.com/studio

下载完成后,打开 Android Studio 并导入您的项目。Android Studio 会自动检测您的项目所需的 Gradle 版本,并提示您进行升级。按照提示进行操作,即可完成 Android Studio 的升级。

如果在 Android Studio 编译时遇到下面的错误报告:

error

您可以参考以下截图,在设置中修改 Gradle 使用的 JDK 17:

fix

完成上述步骤后,您也可以在构建面板中重新执行构建。