Cordova-Android项目升级至API 34的完整解决方案

背景介绍

在将Cordova-Android项目升级到Android 14（API级别34）的过程中，开发者经常会遇到各种构建问题。这些问题通常涉及Java版本、Gradle版本和Android Gradle插件(AGP)之间的兼容性问题。

核心问题分析

当开发者尝试将Cordova-Android项目升级到13.0.0版本并针对API 34进行构建时，可能会遇到以下典型错误：

1. Java版本不兼容错误：Unsupported class file major version 61，这表明系统使用了不兼容的Java版本
2. Gradle版本过低错误：Could not create service of type ScriptPluginFactory
3. Android Gradle插件警告：关于compileSdk版本不匹配的警告信息

完整解决方案

1. 环境准备

首先需要确保开发环境满足以下要求：

• JDK版本：必须使用Java 17（JDK 17）
• Gradle版本：建议使用8.7或更高版本（目前最新为8.9）
• Android Studio：建议使用JellyFish或更高版本

2. 配置更新步骤

按照以下顺序执行升级操作：

1. 更新系统Java环境：

   • 安装JDK 17
   • 设置JAVA_HOME环境变量指向JDK 17安装目录

2. 更新系统Gradle：

   • 下载并安装Gradle 8.7或更高版本
   • 更新PATH环境变量，确保新安装的Gradle优先级高于系统默认版本

3. 修改项目配置：

   • 在config.xml中设置目标SDK版本为34
   • 示例：<preference name="android-targetSdkVersion" value="34"/>

4. 更新Cordova平台：

   • 移除旧版Android平台：cordova platform remove android
   • 添加新版平台：cordova platform add android@13.0.0

5. 更新插件：

   • 检查并更新所有Cordova插件至最新兼容版本

3. Android Studio配置

在Android Studio中需要完成以下操作：

1. 通过SDK Manager更新：

   • 安装Android API 34平台
   • 更新所有SDK工具至最新版本

2. 重要提示：避免通过AGP Upgrade Assistant更新Android Gradle插件

   • Cordova项目对AGP版本有特定要求
   • 自动更新可能导致不兼容问题

常见问题解决

问题1：Java版本不兼容

错误信息：Unsupported class file major version 61

解决方案：

• 确认JAVA_HOME指向JDK 17
• 检查系统PATH中Java相关路径是否正确
• 重启开发环境使更改生效

问题2：Gradle版本过低

错误信息：Could not create service of type ScriptPluginFactory

解决方案：

• 升级系统Gradle至8.7或更高版本
• 验证gradle -v输出显示正确版本
• 确保新版本Gradle在PATH中的优先级

问题3：compileSdk警告

警告信息：We recommend using a newer Android Gradle plugin to use compileSdk = 34

解决方案：

• 完全移除并重新添加Android平台
• 不要手动修改AGP版本
• Cordova会自动配置兼容的AGP版本

最佳实践建议

1. 环境隔离：考虑使用Docker或虚拟环境来管理构建环境，避免系统环境污染
2. 版本控制：将Gradle Wrapper纳入版本控制，确保团队使用相同构建环境
3. 渐进升级：对于大型项目，建议先升级到中间版本（如API 33），再升级到API 34
4. 备份策略：在进行重大升级前，确保有完整的项目备份

通过遵循上述步骤和建议，开发者可以顺利完成Cordova-Android项目到API 34的升级，并避免常见的构建问题。