原生移动开发 / 系统课时

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 决定是否启用新的权限、安全或后台执行规则,所以提高它不仅是改一个数字,还意味着需要验证行为变化。

SDK 配置与设备 API Level 的兼容关系

可以把三者记成三个问题:编译时能看到什么 API、最低在哪些设备上运行、在新系统上按哪套目标行为执行。它们职责不同,不能用提高 compileSdk 来代替兼容性测试,也不能用降低 targetSdk 解决新平台适配问题。

用一个配置看清边界

下面是 app/build.gradle.kts 的片段示例。数值只是教学示例,真实项目应按依赖要求、设备覆盖范围和发布要求选择。

kotlin
android {
    compileSdk = 36

    defaultConfig {
        applicationId = "com.example.compatdemo"
        minSdk = 23
        targetSdk = 36
        versionCode = 1
        versionName = "1.0"
    }
}

这组配置表示:项目使用 API 36 的平台接口参与编译;设备至少需要 API 23 才满足安装下限;应用按 API 36 对应的平台行为作为适配目标。修改后可执行一次构建验证 Gradle 配置是否可被当前环境接受。

bash
./gradlew :app:assembleDebug

预期输出

text
BUILD SUCCESSFUL in <TIME>

Windows 可使用 gradlew.bat :app:assembleDebug。实际耗时和任务明细会因项目与缓存状态不同而变化。

调用新 API 时保护旧设备

即使 compileSdk 足够高,运行中的设备仍可能没有该 API。下面示例在 API 33 及以上执行新分支,旧设备走降级逻辑;Build.VERSION.SDK_INT 读取的是当前设备 API Level。

片段示例:下面函数依赖 Android 运行时,应放在 Android 应用模块源码中,由 Activity、ViewModel 等调用。

kotlin
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 提升当作一次需要测试和验收的平台适配变更。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

SDK、API Level 与兼容性

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通