原生移动开发 / 系统课时
SDK、API Level 与兼容性
SDK、API Level 与兼容性
Android 项目能否安装、能调用哪些系统 API、在新系统上采用哪套行为规则,分别由不同 SDK 配置控制。本课把 API Level、minSdk、compileSdk 与 targetSdk 放到同一模型里,避免把“能编译”“能安装”和“已适配”混为一谈。
学习目标
- 说明 SDK 与 API Level 的关系,并区分平台版本和 API 集合
- 判断
minSdk、compileSdk、targetSdk各自影响的阶段 - 为新 API 编写兼容分支,并理解降低或提高 SDK 值的代价
先分清 SDK 与 API Level
Android SDK 是开发工具与平台文件的集合,其中某个 SDK Platform 对应一个 Android 平台 API 集合。API Level 是这个集合的整数标识,例如 Android 13 对应 API 33。代码是否能引用某个系统 API,取决于编译时使用的 SDK Platform;设备实际能否执行该 API,则取决于设备自身的 API Level。
同一个应用会同时面对“编译环境”和“运行设备”两条版本线,因此不能只看一个数字。项目通常还会安装 Platform-Tools、Build-Tools 等工具,但它们与应用声明支持的最低系统版本不是一回事。
三个 SDK 值分别控制什么
minSdk 是安装与运行下限。设备 API Level 低于它时,应用通常不能安装。这个值越低,可覆盖的旧设备越多,但开发者需要承担更多兼容分支和测试成本。
compileSdk 决定编译器可见的 Android API。提高它可以让代码引用更高版本的平台 API,但不会自动让应用只能安装到新设备。调用高于 minSdk 的 API 时,仍需在运行前判断系统版本或使用兼容库。
targetSdk 表示应用针对哪一代平台行为完成了适配与测试。新 Android 版本可能按 targetSdk 决定是否启用新的权限、安全或后台执行规则,所以提高它不仅是改一个数字,还意味着需要验证行为变化。

可以把三者记成三个问题:编译时能看到什么 API、最低在哪些设备上运行、在新系统上按哪套目标行为执行。它们职责不同,不能用提高 compileSdk 来代替兼容性测试,也不能用降低 targetSdk 解决新平台适配问题。
用一个配置看清边界
下面是 app/build.gradle.kts 的片段示例。数值只是教学示例,真实项目应按依赖要求、设备覆盖范围和发布要求选择。
android {
compileSdk = 36
defaultConfig {
applicationId = "com.example.compatdemo"
minSdk = 23
targetSdk = 36
versionCode = 1
versionName = "1.0"
}
}这组配置表示:项目使用 API 36 的平台接口参与编译;设备至少需要 API 23 才满足安装下限;应用按 API 36 对应的平台行为作为适配目标。修改后可执行一次构建验证 Gradle 配置是否可被当前环境接受。
./gradlew :app:assembleDebug预期输出
BUILD SUCCESSFUL in <TIME>Windows 可使用 gradlew.bat :app:assembleDebug。实际耗时和任务明细会因项目与缓存状态不同而变化。
调用新 API 时保护旧设备
即使 compileSdk 足够高,运行中的设备仍可能没有该 API。下面示例在 API 33 及以上执行新分支,旧设备走降级逻辑;Build.VERSION.SDK_INT 读取的是当前设备 API Level。
片段示例:下面函数依赖 Android 运行时,应放在 Android 应用模块源码中,由 Activity、ViewModel 等调用。
import android.os.Build
fun notificationPermissionHint(): String {
return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
"检查 Android 13+ 的通知权限"
} else {
"旧版本无需运行时通知权限"
}
}调用该函数时,API 33 及以上设备返回“检查 Android 13+ 的通知权限”,更低版本返回“旧版本无需运行时通知权限”。这里的关键不是记住某个版本常量,而是形成规则:编译时允许引用,不代表所有受支持设备都能执行。只要使用了高于 minSdk 才提供的 API,就要确认调用路径是否受版本判断、兼容库或其他降级机制保护。
选择兼容范围时看代价
降低 minSdk 会扩大设备覆盖,但需要增加旧系统测试、兼容分支和依赖约束;提高 targetSdk 会进入更现代的平台行为,需要重新验证权限、后台任务、存储等受行为变更影响的功能;提高 compileSdk 主要扩大可编译 API 范围,同时要确保 Android Gradle Plugin 和依赖版本能够支持对应平台。
因此,SDK 兼容性不是“数字越大越好”或“越低覆盖越广”这么简单。一个可维护的项目应明确设备下限,再保持编译 SDK 足够新,并把每次 targetSdk 提升当作一次需要测试和验收的平台适配变更。