Android版本选择全指南：SDK、AGP、Gradle与JDK兼容配置

做 Android 项目这些年被问得最多的问题里“版本到底怎么选”绝对排得上前三。不管是刚入行的新人还是带过几个项目的老人几乎都在这个坑里栽过跟头。我见过太多团队项目启动时随手填了个 compileSdk、targetSdkGradle 插件版本也是复制粘贴来的结果做到一半发现某个依赖库死活拉不下来或者打包时冒出一堆莫名其妙的资源冲突再或者上线后在某些机型上直接闪退。回头一查全是版本没对齐惹的祸。这篇内容就是想把“Android 项目开发时版本选择”这件事彻底讲透。它不是一个简单的“填个数字”的动作而是一整套涉及 SDK 版本、构建工具版本、依赖库版本、JDK 版本之间相互咬合的决策体系。我会从整体设计思路讲起把每个版本参数背后的含义、相互之间的约束关系、以及实际项目里怎么定这套组合讲清楚再配上可直接抄作业的配置模板和踩坑排查表。不管你是刚接触 Android 构建体系的新手还是想把手头项目版本治理理顺的老手都能从里面找到能直接用的东西。1. 版本选择这件事的整体设计思路很多人把版本选择理解成“选个最新的就行”这个认知本身就是最大的坑。Android 的构建体系是一张网SDK 版本、构建工具版本、依赖库版本、JDK 版本、甚至 Android Studio 的版本彼此之间有严格的兼容区间。你动一个可能牵动一片。所以第一步不是急着填数字而是先建立一套“版本决策”的思维框架。1.1 为什么版本选择是个系统工程而不是单点决策先说说 Android 构建到底是怎么跑起来的。你写的代码经过编译、资源处理、打包、签名最终变成一个 APK 或 AAB。这条链路上每一环都有版本参与JDK 负责编译 Java/Kotlin 代码Gradle 负责调度整个构建流程Android Gradle Plugin简称 AGP负责把 Android 特有的构建逻辑接进 GradlecompileSdk 决定你能调用哪些系统 APItargetSdk 决定系统以什么行为模式对待你的应用minSdk 决定应用能装到多老的设备上而各种依赖库又各自声明了自己要求的 compileSdk 和 AGP 下限。这些版本之间不是并列关系而是有依赖方向的。举个最典型的例子AGP 版本决定了它支持的 Gradle 版本区间也决定了它要求的 JDK 版本还决定了它能配合的最高 compileSdk。你如果选了 AGP 8.x那 JDK 就必须是 17Gradle 也得在 8.x 的对应区间里compileSdk 一般也要跟上 34 左右。反过来如果你因为某些原因必须用 JDK 11那 AGP 就只能停在 7.x 系列compileSdk 也就被限制在 33 上下。这就是为什么我说它是系统工程——任何一个点的选择都会沿着依赖链传导出去。我一般建议团队在项目启动阶段就把这张“版本约束图”画出来哪怕只是写在文档里。因为一旦项目跑起来后面再想动版本成本会高得多。尤其是当依赖库多起来之后某个库悄悄把 compileSdk 要求提到了 34而你项目还停在 33构建就会直接报错报错信息还不一定直白新手很容易卡在这里。1.2 四类版本参数的分层理解为了把这件事讲清楚我把项目里会碰到的版本参数分成四层从下往上依次是运行环境层、构建工具层、编译目标层、依赖库层。这个分层不是官方定义是我自己梳理下来觉得最好理解的一种方式。运行环境层包括 JDK 版本和 Gradle 版本。这两个是“地基”决定了构建能不能跑起来。JDK 是 Java 运行环境Gradle 本身也是跑在 JVM 上的所以 JDK 版本选错Gradle 直接起不来。这一层的选择相对刚性主要看 AGP 的要求。构建工具层就是 AGP 版本它是连接 Gradle 和 Android 构建逻辑的桥梁。AGP 的版本节奏跟 Android Studio 是绑定的一般升级 Android Studio 时会提示你升 AGP。这一层的选择要考虑团队用的 IDE 版本、CI 环境的稳定性不能盲目追新。编译目标层包括 compileSdk、targetSdk、minSdk 三个。compileSdk 是“我用哪个版本的 SDK 来编译”targetSdk 是“我告诉系统我适配到了哪个版本”minSdk 是“我最低支持到哪个版本”。这三个经常被混淆后面我会专门拆开讲。依赖库层就是各种第三方库和官方库的版本。这一层最容易被忽视因为库的版本是跟着库自己走的但它对上面三层有硬性要求。一个库如果要求 compileSdk 34你项目是 33那就没得商量要么升项目要么换库版本。把这四层想清楚你在做版本决策时就不会东一榔头西一棒子而是知道先定哪层、再定哪层。我的习惯是先定运行环境层JDK Gradle再定构建工具层AGP然后定编译目标层最后用依赖库层去校验和微调。这个顺序的好处是每一层定下来之后下一层的可选范围就自动收窄了决策成本大幅降低。1.3 稳定优先还是尝鲜优先团队场景下的取舍逻辑版本选择还有一个绕不开的取舍到底用稳定版还是尝鲜版。这个问题没有标准答案得看项目阶段和团队情况。对于大多数业务项目我的建议是“稳定优先滞后一个小版本”。意思是当 AGP 或 compileSdk 出了新版本不要第一时间跟等它发布一两个补丁版本、社区反馈稳定了再升。原因很现实新版本刚出来时各种兼容性问题、构建脚本不兼容、依赖库还没跟上这些坑都要有人先踩。业务项目的时间成本经不起这么折腾。但如果是技术预研项目、或者团队有专门的基建同学维护构建体系那适当尝鲜是合理的可以提前发现迁移成本为后续升级铺路。我待过的一个团队就是每季度做一次版本升级演练在独立分支上把 AGP、compileSdk 都升到最新跑一遍完整构建和测试记录下所有报错和改动点。这样等真正要升的时候心里有底不会手忙脚乱。还有一个容易被忽略的点是 CI 环境的版本一致性。本地开发用一套版本CI 上用另一套这是很多“本地能跑、CI 挂掉”问题的根源。所以版本选择不只是本地的事要把 CI 的 JDK、Gradle 缓存、构建镜像都纳入考虑。我一般会在项目根目录放一个版本清单文件本地和 CI 都从同一个地方读版本号保证一致性。2. 核心版本参数逐个拆解与实操要点上一节讲了整体框架这一节把每个核心参数单独拎出来讲透。每个参数我都会说清楚它是什么、怎么选、选错了会怎样以及实际配置时要注意什么。这部分是整篇内容的核心建议对照着自己项目的配置文件看。2.1 compileSdk、targetSdk、minSdk 到底怎么区分这三个参数是新手最容易搞混的我见过有人把 targetSdk 当成 compileSdk 填也见过有人以为 minSdk 越低越好。先把定义摆清楚。compileSdk是编译时使用的 Android SDK 版本。它决定了你的代码能调用哪些系统 API。比如你想用某个在 API 34 才引入的新接口那 compileSdk 就必须是 34 或更高否则编译器直接报“找不到符号”。它只影响编译不影响运行时行为。你可以理解为“我参考的是哪一版说明书来写代码”。targetSdk是告诉系统“我这个应用已经适配到了哪个版本”。系统会根据这个值决定用哪套行为模式来对待你的应用。比如从某个版本开始系统对后台权限、通知、存储访问的行为有变化如果你的 targetSdk 达到了那个版本系统就会按新行为执行如果没达到系统会走兼容模式。所以 targetSdk 直接关系到应用在新系统上的实际表现是上架应用市场时的硬性要求各大应用市场都会要求 targetSdk 达到一定版本以上。minSdk是应用支持的最低系统版本。低于这个版本的设备装不上你的应用。它决定了你的用户覆盖面也决定了你能用哪些 API 而不用做版本判断。minSdk 定得越低覆盖的设备越多但你要做的兼容处理也越多而且很多新库会要求较高的 minSdk。三者的关系可以这样理解minSdk 是地板targetSdk 是天花板的行为标准compileSdk 是你手里的工具书版本。compileSdk 一般要大于等于 targetSdk因为你要用新版 SDK 编译才能声明适配到那个版本。minSdk 则要小于等于 targetSdk。实际选择时我的经验是这样compileSdk 跟着 AGP 和依赖库的要求走一般用当前稳定版的最新 SDKtargetSdk 跟着应用市场的要求走市场要求多少就至少填多少可以适当超前minSdk 则要结合用户数据和依赖库要求来定现在主流做法是定在 21 到 24 之间太低会拖累依赖库选择太高会丢用户。注意compileSdk 升级后一定要同步检查所有依赖库是否支持。有些老库在新 compileSdk 下会有资源冲突或 API 变更导致的编译错误这时候要么升级库版本要么找替代方案。2.2 AGP 与 Gradle 的版本咬合关系AGP 和 Gradle 的关系是“插件与宿主”。Gradle 是通用构建工具AGP 是跑在 Gradle 上的 Android 专用插件。所以 AGP 对 Gradle 版本有明确的最低要求也有最高兼容限制。这个对应关系在官方文档里有表格但很多人不看直接复制别人的配置结果版本对不上构建报错。我整理了一份常见版本的对应关系方便对照。需要说明的是这只是基于常见实践的归纳具体以官方发布说明为准。AGP 版本最低 Gradle 版本推荐 JDK 版本建议 compileSdk7.0.x7.0.211317.4.x7.511338.0.x8.017338.1.x8.017348.2.x8.217348.3.x8.41734从这张表能看出一个明显的分水岭AGP 8.0 开始强制要求 JDK 17。这是很多团队升级时最大的拦路虎因为本地开发环境和 CI 环境都要跟着换 JDK。我见过有团队为了不升 JDK硬是把 AGP 卡在 7.4结果新依赖库用不了最后还是要升白白浪费了时间。配置 AGP 版本的位置在项目根目录的build.gradle或build.gradle.kts里的plugins块或buildscript块。Gradle 版本则在gradle/wrapper/gradle-wrapper.properties文件里的distributionUrl指定。这两个地方要一起改只改一个会出问题。// 项目根目录 build.gradle 片段 plugins { id com.android.application version 8.2.2 apply false id com.android.library version 8.2.2 apply false }# gradle/wrapper/gradle-wrapper.properties distributionUrlhttps\://services.gradle.org/distributions/gradle-8.2-bin.zip提示升级 AGP 时先改 Gradle wrapper 版本再改 AGP 版本顺序反了容易在同步阶段就报错排查起来更麻烦。2.3 JDK 版本被低估的构建地基JDK 版本在版本选择里经常被忽略因为很多人觉得“能编译就行”。但 AGP 8.x 强制 JDK 17 之后这个参数的重要性一下子凸显出来了。JDK 版本不对Gradle 可能直接启动失败报错信息往往是“Unsupported class file major version”之类新手看了完全摸不着头脑。JDK 版本的选择逻辑很简单跟着 AGP 的要求走。AGP 7.x 及以下用 JDK 11 就行AGP 8.x 必须 JDK 17。这里要注意的是JDK 版本有三个地方要统一本地开发环境的 JAVA_HOME、Android Studio 里配置的 Gradle JDK、CI 构建环境用的 JDK。这三处不一致就会出现“本地能跑 CI 挂”的经典问题。还有一个细节是 Java 语言级别的配置。在模块的build.gradle里compileOptions和kotlinOptions里的jvmTarget要和 JDK 版本匹配。比如用 JDK 17那sourceCompatibility、targetCompatibility、jvmTarget都应该是 17。如果这里填的还是 1.8虽然有时能编译通过但会遇到一些奇怪的字节码问题。// 模块级 build.gradle 片段 android { compileOptions { sourceCompatibility JavaVersion.VERSION_17 targetCompatibility JavaVersion.VERSION_17 } kotlinOptions { jvmTarget 17 } }我踩过的一个坑是本地装了多个 JDK 版本环境变量指向的是 11但 Android Studio 里 Gradle JDK 配的是 17结果命令行构建和 IDE 构建行为不一致排查了半天才发现是 JDK 来源不同。所以建议团队统一用版本管理工具管理 JDK或者在项目文档里明确写清楚用哪个 JDK 路径。2.4 依赖库版本最容易被忽视的约束源依赖库版本是版本选择里最动态、最难控的一环。因为每个库都有自己的发布节奏和版本要求你项目里几十个依赖任何一个升级都可能带来连锁反应。尤其是那些传递依赖你直接依赖的库 A 可能又依赖了库 B 的某个版本而库 B 又对 compileSdk 有要求这种间接约束很容易被忽略。处理依赖库版本我的核心原则是“统一管理、显式声明、定期体检”。统一管理是指把所有依赖版本集中到一个地方比如用 Gradle 的 version cataloglibs.versions.toml或者根目录的ext块避免各个模块各写各的。显式声明是指不要依赖传递依赖的版本重要的库要自己显式指定版本防止被其他库的传递依赖带偏。定期体检是指定期跑./gradlew dependencies看依赖树发现版本冲突及时处理。版本冲突的典型表现是构建时报“Duplicate class”或者运行时找不到方法。前者是同一个类出现在多个依赖里后者是编译时用的版本和运行时用的版本不一致。排查这类问题./gradlew :app:dependencies是必备命令它能打印出完整的依赖树标出哪些版本被提升了、哪些被降级了。# 查看 app 模块的依赖树 ./gradlew :app:dependencies --configuration releaseRuntimeClasspath对于依赖库版本的选择策略我一般分三类处理官方库如 AndroidX 系列跟着 compileSdk 走用较新的稳定版主流第三方库如网络、图片加载类用社区验证充分的稳定版不追最新小众库或长期不维护的库要重点评估看它要求的 compileSdk 和 AGP 下限是否和项目匹配不匹配就考虑替换。注意依赖库升级后一定要跑完整回归测试尤其是涉及网络、存储、权限的库。有些库的小版本升级会悄悄改变默认行为不测根本发现不了。3. 从零搭建一套版本配置的完整实操前面讲了原理和参数这一节把整套流程串起来从零开始搭一套可用的版本配置。我会按实际操作顺序走一遍每一步说清楚做什么、为什么这么做、怎么验证。这套流程适用于新项目启动也适用于老项目的版本治理。3.1 第一步确定 JDK 与 Gradle 基线动手配任何东西之前先把 JDK 和 Gradle 定下来。这一步的输入是“团队现有环境”和“目标 AGP 版本”。假设我们要用 AGP 8.2.x那 JDK 必须是 17Gradle 至少 8.2。先确认本地 JDK。命令行执行java -version看输出是不是 17。如果不是装一个 17 的 JDK把JAVA_HOME指过去。然后在 Android Studio 的 Settings 里找到 Build Tools 下的 Gradle把 Gradle JDK 也设成 17。这两处必须一致。接着配 Gradle wrapper。在项目根目录执行gradle wrapper --gradle-version 8.2或者直接改gradle-wrapper.properties里的distributionUrl。改完之后执行./gradlew --version确认输出的 Gradle 版本和 JVM 版本都对。这一步的验证标准很简单./gradlew --version能正常输出且 JVM 显示 17。如果报错大概率是 JDK 没配对回去检查JAVA_HOME和 IDE 配置。3.2 第二步锁定 AGP 与 compileSdk 组合JDK 和 Gradle 就位后配 AGP。在根目录build.gradle的plugins块里声明 AGP 版本模块级build.gradle里应用插件。然后配 compileSdk一般用当前稳定版的最新 SDK比如 34。这里有个实操细节compileSdk 升级后Android Studio 可能会提示你安装对应版本的 SDK Platform。别跳过一定要装否则编译时会报找不到 android.jar。装完之后同步项目看有没有报错。同步通过后先别急着写业务代码跑一次空构建./gradlew assembleDebug确认整条链路是通的。这一步能提前暴露版本不匹配的问题比写到一半再发现要好得多。3.3 第三步配置 targetSdk 与 minSdk 的取值targetSdk 的取值看应用市场要求。假设当前市场要求 targetSdk 至少 33那我们就填 33或者直接填 34 超前一点。填之前要想清楚targetSdk 提升会带来行为变更比如权限申请方式、后台限制、存储访问规则等。所以提升 targetSdk 不是改个数字就完事要对照官方的行为变更清单逐项检查。minSdk 的取值要结合用户数据。如果应用的目标用户里还有不少老设备minSdk 可以定低一点比如 21。但要注意minSdk 定得低一些新库就用不了因为它们可能要求 minSdk 23 或更高。我的做法是先看核心依赖库的 minSdk 要求取其中最高的作为项目 minSdk 的下限再结合用户数据往上调。配置位置在模块级build.gradle的defaultConfig块里android { compileSdk 34 defaultConfig { minSdk 24 targetSdk 34 // 其他配置 } }3.4 第四步依赖库版本的统一收口依赖库版本管理我强烈建议用 version catalog。它是 Gradle 官方提供的集中管理依赖版本的方式配置文件是gradle/libs.versions.toml。把所有依赖的版本、库坐标、插件都写在这个文件里各模块引用别名即可。好处是版本一目了然改一处全局生效还能被 IDE 自动补全。一个典型的libs.versions.toml长这样[versions] agp 8.2.2 kotlin 1.9.22 coreKtx 1.12.0 appcompat 1.6.1 material 1.11.0 [libraries] androidx-core-ktx { group androidx.core, name core-ktx, version.ref coreKtx } androidx-appcompat { group androidx.appcompat, name appcompat, version.ref appcompat } material { group com.google.android.material, name material, version.ref material } [plugins] android-application { id com.android.application, version.ref agp } kotlin-android { id org.jetbrains.kotlin.android, version.ref kotlin }模块里引用时写implementation(libs.androidx.core.ktx)即可。这样所有版本集中在一处升级时只改 toml 文件清晰可控。配好之后跑./gradlew :app:dependencies检查依赖树重点看有没有版本冲突标记通常显示为-表示版本被提升。如果有冲突根据实际情况决定是统一版本还是排除某个传递依赖。3.5 第五步构建验证与版本清单固化所有配置完成后做一轮完整验证清理构建./gradlew clean然后./gradlew assembleDebug和./gradlew assembleRelease都跑一遍确保 debug 和 release 都能出包。再跑一遍单元测试./gradlew test确认没有因版本变更导致的测试失败。验证通过后把当前这套版本组合固化下来写进项目文档或者 README。内容包括JDK 版本、Gradle 版本、AGP 版本、compileSdk、targetSdk、minSdk、核心依赖库版本。这份清单是后续升级的基线也是新人接手项目时的第一手资料。我还会在 CI 配置里加一个检查步骤构建前先打印./gradlew --version和关键版本号方便出问题时快速定位环境差异。这个习惯帮我省了很多排查时间。4. 版本问题排查实录与避坑清单版本相关的报错很多都长得差不多但根因各不相同。这一节我把实际项目中遇到过的典型问题整理出来配上排查思路和解决方法做成速查表方便对照使用。4.1 常见报错与根因对照表报错关键词可能根因排查方向解决方式Unsupported class file major versionJDK 版本与 AGP/Gradle 不匹配检查./gradlew --version的 JVM 版本统一 JDK 到 AGP 要求的版本Minimum supported Gradle version is XGradle 版本低于 AGP 要求看 AGP 版本对应的最低 Gradle升级 gradle-wrapper 版本Duplicate class依赖库版本冲突跑依赖树看重复类来源排除传递依赖或统一版本Failed to resolve: com.xxx依赖库版本不存在或仓库配置问题检查版本号拼写和仓库地址修正版本号或添加仓库compileSdkVersion is not specified模块未配置 compileSdk检查模块 build.gradle补上 compileSdk 配置This version of the Android Support plugin requires...AGP 与 IDE 版本不匹配看 IDE 版本和 AGP 要求升级 IDE 或降 AGPresource linking failedcompileSdk 与依赖库资源不兼容看报错涉及的资源来源升级 compileSdk 或降依赖库版本这张表覆盖了大部分高频问题。实际排查时我的习惯是先看报错的第一行和最后一行第一行往往是根因最后一行是表象。然后对照表格定位方向再用具体命令验证。4.2 三个真实踩坑案例的复盘第一个坑是 JDK 版本不一致导致的“本地能跑 CI 挂”。当时项目本地用 JDK 17CI 镜像里默认是 JDK 11构建时报了一堆看不懂的字节码错误。排查了半天才发现是 CI 环境 JDK 没配对。后来我们在 CI 脚本里显式指定 JDK 路径并在构建前打印版本信息这类问题再没出现过。第二个坑是依赖库传递依赖引发的 compileSdk 冲突。项目 compileSdk 是 33某个新引入的库传递依赖了一个要求 compileSdk 34 的库构建直接失败。报错信息指向的是那个传递依赖的库但我们在自己的依赖声明里根本找不到它。最后靠./gradlew :app:dependencies一层层往上找才定位到是哪个直接依赖带进来的。解决方式是把那个直接依赖降到不要求 34 的版本。第三个坑是 targetSdk 提升后的运行时行为变化。项目把 targetSdk 从 32 提到 33 后测试发现通知权限的申请逻辑失效了。原因是新版本对通知权限的处理方式变了需要显式申请。这种问题编译期发现不了只能靠测试覆盖。所以提升 targetSdk 一定要配完整的回归测试尤其是涉及权限、存储、后台的模块。4.3 版本升级的稳妥操作节奏版本升级最怕“一把梭”改一堆版本然后构建失败根本不知道是哪个改动引起的。我的建议是分步走每步验证。先升 Gradle wrapper单独验证构建能跑通。再升 AGP验证同步和构建。然后升 compileSdk验证编译和资源处理。接着升 targetSdk跑回归测试。最后升依赖库逐个升、逐个测。每一步都提交一次代码出问题能快速回滚到上一个可用状态。这个节奏看起来慢但实际比“改一堆再排查”要快得多。我见过团队一次性把所有版本升到最新结果构建报了几十个错排查了两天才理清楚反而更费时间。提示升级前先在独立分支操作主分支保持稳定。升级分支上每完成一步就提交形成清晰的提交历史方便回溯。4.4 团队协作下的版本一致性保障最后说说团队协作。版本问题在单人开发时还好多人协作时会被放大。A 同学本地 JDK 17B 同学 JDK 11C 同学的 IDE 又配了另一套三个人构建行为都不一样代码合并后问题频出。保障一致性的核心是“版本来源唯一”。JDK 版本写进项目文档和 CI 配置Gradle 版本由 wrapper 锁定wrapper 文件要提交到仓库AGP 和依赖库版本由 version catalog 统一管理。新人入职第一件事就是按文档配环境配完跑一次./gradlew --version和空构建验证。另外可以在项目里加一个简单的版本检查脚本构建前自动比对关键版本是否符合预期不符合就给出提示。这个脚本不复杂但能挡住很多低级问题。#!/bin/bash # 简单的版本检查脚本示例 expected_jdk17 actual_jdk$(java -version 21 | head -1 | grep -oE [0-9] | head -1) if [ $actual_jdk ! $expected_jdk ]; then echo 警告当前 JDK 版本为 $actual_jdk项目要求 $expected_jdk exit 1 fi echo JDK 版本检查通过这套机制跑顺之后版本问题基本就从“反复踩坑”变成了“偶发可控”。我个人在实际操作中的体会是版本选择这件事前期多花半天把基线定清楚后期能省下好几天的排查时间。尤其是团队项目把版本清单和检查机制建起来比任何单点的技术技巧都管用。