SDK Platform：定义、版本与Android SDK Manager

什么是SDK Platform

SDK Platform — 是Android SDK的基础组件，代表了针对特定Android版本开发应用程序的完整库和工具集。每个平台通过API Level进行标识——一个随着新操作系统版本发布而增加的整数。例如，Android 13对应API Level 33，Android 14对应API Level 34，Android 15对应API Level 35。

与Android Studio（IDE）不同，SDK Platform不包含代码编辑器或调试器。它是一个连接到编译器和构建工具的系统层。当开发者编写import android.app.Activity时，编译器从特定SDK Platform的android.jar中获取该类。如果没有安装具有所需API Level的平台，代码将无法编译。

Google为每个稳定的Android版本发布一个新的SDK Platform。历史涵盖超过35个API Level——从Android 1.0（API 1）到Android 15（API 35）。每个平台向后兼容：为API Level 21编写的代码将在API Level 35上运行，但反之则不然。

为什么每个版本都需要单独的SDK Platform

Android发展迅速：每个版本都会添加新的API、更改现有API的行为并引入限制。例如，Android 10（API 29）引入了Scoped Storage，Android 12（API 31）引入了SplashScreen API，Android 14（API 34）引入了强制性的BroadcastReceiver标志。开发者必须针对当前平台构建应用程序才能使用这些功能。

同时，应用程序可以在旧版操作系统上运行。为此，在Gradle中指定minSdk——应用程序运行的最低API Level。代码使用版本检查和条件API调用。这种方法在保留新功能的同时确保了兼容性。

SDK Platform的组成：主要组件

SDK Platform——不是单个文件，而是一组共同提供应用程序编译、构建和测试的组件。主要元素是android.jar——包含此版本中Android API类的归档文件。该文件连接到Kotlin或Java编译器，并确定开发者可以使用哪些类、方法和注解。

系统镜像和模拟器

每个SDK Platform都包含System Image——用于Android Virtual Device模拟器的操作系统镜像。如果没有相应的镜像，模拟器将无法启动具有所需API Level的虚拟设备。System Images有多种类型：Google APIs（带Google服务）、Google Play（带Play Store）和AOSP（不带Google服务的纯净Android）。

构建和调试工具

SDK Platform包含针对该API Level优化的Build-Tools和Platform-Tools版本。Build-Tools包括aapt2（Android Asset Packaging Tool）、dx/d8（Dalvik/ART编译器）和ApkSigner。Platform-Tools提供ADB（Android Debug Bridge）、fastboot和SQLite。这些工具通过SDK Manager独立于SDK Platform进行更新。

平台资源

每个平台都包含标准的Android资源——系统主题、样式、动画、颜色和尺寸。这些资源在编译时使用：如果开发者引用@android:style/Theme.Material.Light，构建工具会从SDK Platform资源中获取定义。这保证了所有设备上系统组件外观的一致性。

API Level与SDK Platform版本

API Level — 是Android SDK版本的整数标识符。每个Android版本对应一个单调递增的API Level。开发者在build.gradle的三个关键参数中指定API Level：compileSdk、minSdk和targetSdk。这些参数的选择决定了哪些API可用以及系统如何处理应用程序。

Google建议将minSdk保持在当前分发阈值以上——根据Android Studio Distribution Dashboard（2026），约95%的设备运行在Android 8.0（API 26）及以上版本。compileSdk应为最新的稳定版——这可以访问新的API，并允许lint检查检测不推荐的方法。

API Level的演变：关键变化

随着每个新的API Level，Google都会引入重大变化。Android 6.0（API 23）添加了运行时权限——应用程序在运行时请求权限，而不是在安装时。Android 8.0（API 26）引入了表单自动填写和通知渠道。Android 12（API 31）从根本上改变了对intent的处理方式——出现了SplashScreen API和通过exported属性导出组件。Android 14（API 34）强制要求指定BroadcastReceiver的标志，并对前台服务引入了严格限制。

了解API Level的历史有助于开发者选择正确的兼容性策略。如果应用程序使用compileSdk 35但minSdk 26，代码只能在通过Build.VERSION.SDK_INT检查版本后才能调用API 35的方法。这种方法称为version-gated development，是行业标准。

SDK Manager：安装与配置

SDK Manager — 是用于管理Android SDK组件的工具：安装新的SDK Platform、更新现有的以及删除过时的。SDK Manager既可作为Android Studio中的图形界面使用，也可通过sdkmanager命令行使用。通过命令行，SDK Manager非常适合在没有图形界面的CI/CD流水线中使用。

SDK Manager将平台安装到Android SDK目录中，默认情况下位于Linux和macOS的$HOME/Android/Sdk或Windows的%LOCALAPPDATA%\Android\Sdk。在platforms目录内有android-{API Level}格式的文件夹，每个文件夹包含完整的SDK Platform。

通过sdkmanager安装SDK Platform

sdkmanager命令接受"platforms;android-{API}"格式的包标识符。例如，安装SDK Platform 35的命令如下：

# 为API Level 35安装SDK Platform
sdkmanager "platforms;android-35"

# 用一个命令安装多个平台
sdkmanager "platforms;android-34" "platforms;android-33" "platforms;android-31"

# 已安装的平台列表
sdkmanager --list_installed | grep platforms

# 删除过时的平台
sdkmanager --uninstall "platforms;android-28"

通过Gradle自动安装

现代Android项目使用Gradle Plugin，它可以在首次构建时自动安装SDK Platform。为此，需要在build.gradle中指定compileSdk，并在本地配置中添加SDK目录。Android Studio在打开项目时也会提供安装缺失平台的选项——只需在Gradle同步窗口中点击"Install SDK Platform"按钮即可。

定期通过SDK Manager更新SDK Platform很重要——随着平台一起更新的还有Build-Tools和Platform-Tools，这会影响构建性能和调试稳定性。Google建议每2-3周检查一次SDK更新，尤其是在Google Play上发布新版本应用之前。

为模拟器配置系统镜像

要启动具有特定API Level的模拟器，需要安装相同版本的System Image。SDK Manager允许下载不同架构（x86_64、arm64-v8a）和类型（Google APIs、Google Play、AOSP）的镜像。下载镜像后，AVD Manager基于该镜像创建虚拟设备。

# 安装带Google APIs的System Image（适用于API 35）
sdkmanager "system-images;android-35;google_apis;x86_64"

# 通过命令行创建AVD
avdmanager create avd -n pixel8 -k "system-images;android-35;google_apis;x86_64"

# 已创建的AVD列表
avdmanager list avd

Gradle中的compileSdk、targetSdk和minSdk

build.gradle中的三个参数决定了应用程序与SDK Platform的交互方式。compileSdk — 用于编译的API Level。该参数指定了代码中可用的Android API类。compileSdk应该是三者中最新的，并且不影响运行时行为——应用程序可以编译，但只使用设备上存在的API。

minSdk — 应用程序可以安装的最低API Level。Google Play不允许在版本低于minSdk的设备上安装应用程序。该参数决定了兼容性阈值并影响受众覆盖范围。minSdk越低，支持的设备越多，但无需检查即可使用的新API就越少。

targetSdk — 应用程序测试所针对的API Level。Android系统使用targetSdk来应用行为变更：如果应用程序未更新到新的API Level，系统会为旧版本启用兼容模式。Google Play要求targetSdk不低于特定级别——2026年为API 34（Android 14）。

Gradle配置示例

android {
    compileSdk 35

    defaultConfig {
        applicationId "com.example.app"
        minSdk 26
        targetSdk 35
        versionCode 1
        versionName "1.0"
    }

    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
        targetCompatibility JavaVersion.VERSION_17
    }
}

// Android SDK版本必须通过SDK Manager安装
// sdkmanager "platforms;android-35"

如何选择compileSdk、minSdk和targetSdk

选择策略取决于项目目标。对于新应用程序：compileSdk——最新的稳定版（2026年初为35），minSdk——API 26（Android 8.0，覆盖95%的设备），targetSdk——最新的稳定版。对于更新现有应用程序：立即提高compileSdk，targetSdk——在测试完所有行为变更后，minSdk——仅在需要放弃老旧设备时。

Google要求在每年Android新版本发布后一年内更新targetSdk。不满足此要求的应用程序无法在Google Play上发布更新。请使用官方的Android OS更新日历跟踪截止日期。

代码中使用SDK Platform的示例

在为不同Android版本开发时，需要考虑API的可用性。如果应用程序使用compileSdk 35但在API 31的设备上运行，调用API 34中添加的方法将导致NoSuchMethodError或AbstractMethodError。通过Build.VERSION.SDK_INT进行版本检查可安全地调用新API。

在运行时检查API Level

class FeatureChecker {
    fun registerNotificationChannel(context: Context) {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
            // Notification channels从API 26开始可用
            val channel = NotificationChannel(
                "updates",
                "更新",
                NotificationManager.IMPORTANCE_DEFAULT
            )
            val manager = context.getSystemService(NotificationManager::class.java)
            manager.createNotificationChannel(channel)
        }
    }
}

使用@RequiresApi调用新API

对于仅在特定版本上调用的方法，使用@RequiresApi注解。这告诉lint检查该方法安全，并禁用警告。结合SDK_INT检查，该注解使代码更简洁，更易于审查者理解。

@RequiresApi(Build.VERSION_CODES.UPSIDE_DOWN_CAKE)
fun scheduleExactAlarm(manager: AlarmManager, time: Long) {
    // API 34：使用SCHEDULE_EXACT_ALARM标志的scheduleExact
    if (manager.canScheduleExactAlarms()) {
        manager.setExact(AlarmManager.RTC_WAKEUP, time, pendingIntent)
    } else {
        // 请求SCHEDULE_EXACT_ALARM权限
        val intent = Intent(Settings.ACTION_REQUEST_SCHEDULE_EXACT_ALARM)
        context.startActivity(intent)
    }
}

fun safeScheduleAlarm(context: Context, triggerTime: Long) {
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
        scheduleExactAlarm(getAlarmManager(context), triggerTime)
    } else {
        // 未检查权限的旧setExact方法
        getAlarmManager(context).setExact(AlarmManager.RTC_WAKEUP, triggerTime, pendingIntent)
    }
}

确定已安装的SDK Platform

有时需要了解开发者的设备或CI中安装了哪个版本的SDK Platform。这可以通过ADB或在应用程序代码中以编程方式完成。了解设备的API Level有助于测试特定版本的行为。

fun logDeviceInfo() {
    with (Build.VERSION) {
        Log.d("SDK_Demo", "SDK_INT: $SDK_INT")
        Log.d("SDK_Demo", "RELEASE: $RELEASE")
        Log.d("SDK_Demo", "CODENAME: $CODENAME")
        Log.d("SDK_Demo", "PREVIEW_SDK_INT: $PREVIEW_SDK_INT")
    }
    // 输出：SDK_INT: 35, RELEASE: 15, CODENAME: REL
}