Android开发中SDK的版本及注意事项

发表于 | 分类于
Android开发中SDK的版本及注意事项

前言

打开老的项目，发现gradle中报红：

Google Play requires that apps target API level 33 or higher.

要求我们targetSdkVersion版本必须最低33。

这几个版本到底什么关系呢？

  • minSdkVersion
  • targetSdkVersion
  • compileSdkVersion
  • buildToolsVersion

build.gradle.kts

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
android {
    namespace = "com.xhkjedu.zxs_android"
    compileSdk = 36

    defaultConfig {
        applicationId = "com.xhkjedu.zxs_android"
        minSdk = 31
        targetSdk = 36
        versionCode = 17
        versionName = "1.0.17"

        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
    }

    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_11
        targetCompatibility = JavaVersion.VERSION_11
    }
    kotlinOptions {
        jvmTarget = "11"
    }
}

build.gradle

1
2
3
4
5
6
7
8
9
10
11
12
13
android {
    compileSdkVersion 30
    buildToolsVersion "30.0.1"
    defaultConfig {
        applicationId "com.xhly.easystud"
        minSdkVersion 21
        targetSdkVersion 29
        multiDexEnabled true
        versionCode 608
        versionName "3.14.9"
        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
    }
}

参数作用

明确每个参数的本质功能，这是理解关系的基础：

参数名 核心定义 关键作用 示例（你的配置）
minSdkVersion 应用支持的 最低 Android 系统版本（API Level） 1. 决定应用能安装到哪些设备（低于此版本的设备无法安装）；2. 限制代码中可调用的 API（低于此 API Level 的方法会报错）；3. 是 “向下兼容” 的底线。 21 → 最低支持 Android 5.0（Lollipop）
targetSdkVersion 应用 目标适配的 Android 系统版本（API Level） 1. 声明应用 “已在该版本上充分测试”，系统会按此版本的规则运行（如权限、行为逻辑）；2. 不限制安装设备（只要≥minSdkVersion 即可），但影响系统特性的兼容性；3. 是 “向上兼容” 的 “适配标杆”。 29 → 目标适配 Android 10（Q）
compileSdkVersion 编译应用时使用的 Android SDK 版本（API Level） 1. 决定编译器使用哪个版本的 SDK 源码、API 接口进行编译；2. 控制能否使用高版本 API（需配合@RequiresApi注解做兼容性处理）；3. 必须 ≥ targetSdkVersion（否则编译报错），是 “编译阶段” 的核心。 30 → 使用 Android 11（R）的 SDK 编译
buildToolsVersion 编译工具（如 aapt、dx）的 版本号 1. 提供编译、打包、优化 APK 的工具集；2. 版本格式为X.Y.Z（X 对应 compileSdkVersion 的主版本）；3. 需与 compileSdkVersion 匹配（通常推荐使用对应 SDK 的最新构建工具）。 30.0.1 → 配合 compileSdkVersion 30 使用

版本的大小关系

minSdkVersion ≤ targetSdkVersion ≤ compileSdkVersion

buildToolsVersion

自 Android Gradle Plugin 3.0 起，buildToolsVersion 可省略（会自动匹配 compileSdkVersion 的最新推荐版本），但手动指定时需确保主版本一致。

推荐配置

  1. compileSdkVersion 尽可能高：

    直接使用当前 Android Gradle Plugin（AGP）支持的 最新稳定版 SDK（如 2024 年主流是 34/35）。

    • 原因：高版本 SDK 包含最新 API、编译优化和安全检查，能提前适配新系统特性（如 Android 14 的运行时权限强化），且不影响低版本设备运行（需配合兼容性处理）。
    • 注意：需与 AGP 版本兼容（如 AGP 8.0+ 推荐 compileSdkVersion ≥ 33）。

  2. targetSdkVersion 等于 compileSdkVersion：

    保持与 compileSdkVersion 一致（或至少不低于当前主流系统版本，如 2024 年建议 ≥ 33）。

    • 原因：声明 “应用已适配最新系统”，系统会按最新规则运行（如 Android 13 的通知权限、Android 14 的后台启动限制），避免因 “兼容模式” 导致功能异常。
    • 例外：若需快速适配旧版本，可暂时低于 compileSdkVersion，但需在 1-2 个版本内跟进升级。

  3. minSdkVersion 按需选择，兼顾用户量与功能：

    根据应用受众和核心功能选择最低支持版本，参考 Google Play 设备分布数据（2024 年 Android 7.0+ 占比超 95%）。

    • 大众应用：推荐 ≥ 24（Android 7.0），覆盖绝大多数设备，同时支持 MultiWindow、FileProvider 等基础现代特性。
    • 工具类 / 小众应用：可放宽至 21（Android 5.0），但需额外处理旧系统兼容（如矢量图兼容、权限适配）。
    • 高端功能应用（如 Jetpack Compose）：需 ≥ 21（Compose 最低要求），若用 Compose Material3 高级特性，建议 ≥ 26。

  4. buildToolsVersion 省略或匹配 compileSdkVersion：

    自 AGP 3.0 起，可完全省略该参数（Gradle 会自动匹配 compileSdkVersion 对应的最新构建工具）。

    • 若手动指定，格式为 X.Y.Z（X 需与 compileSdkVersion 一致，如 compileSdk=34 → buildTools=34.0.0）。

Android和SDK版本对应

每个 Android 版本都会对应一个主要 SDK 版本（API 级别），同时可能在后续更新中兼容更高的 API 级别（通过系统更新或 Google Play 服务扩展）。

以下是近年来的核心对应关系：

Android 版本 版本号 对应 SDK 版本（API 级别） 发布时间 关键特性
Android 14 14 API 34 2023-08 隐私增强、UI 自定义、健康连接 API 扩展
Android 13 13 API 33 2022-08 照片选择器、通知权限、主题动态颜色
Android 12L 12.1 API 32 2022-03 平板 / 折叠屏优化、系统 UI 适配
Android 12 12 API 31 2021-10 Material You 设计、隐私权限（如麦克风 / 摄像头单次授权）
Android 11 R API 30 2020-09 气泡通知、权限自动重置、存储访问框架优化
Android 10 Q API 29 2019-09 隐私增强（位置权限细化）、深色模式、手势导航
Android 9 Pie API 28 2018-08 刘海屏适配、室内定位、神经网络 API
Android 8.1 Oreo API 27 2017-12 图片 PIP 模式、蓝牙 5.0 支持
Android 8.0 Oreo API 26 2017-08 通知渠道、自适应图标、后台限制
Android 7.1 Nougat API 25 2016-10 圆形图标支持、快捷方式
Android 7.0 Nougat API 24 2016-08 分屏多任务、通知直接回复
Android 6.0 Marshmallow API 23 2015-10 运行时权限、指纹识别、Doze 省电模式