compileSdkVersion：基础知识、新 API 和 Gradle 配置

Android 中的 compileSdkVersion 是什么？

compileSdkVersion — build.gradle 中的一个整型参数，指定代码应针对哪个 Android SDK 版本进行编译。当您编写使用 android.* 或 androidx.* 中的类的代码时，编译器会将其与指定 compileSdk 版本中可用的 API 进行核对。如果某个方法出现在 API 36 中而 compileSdk = 35，则代码将无法编译。如果 compileSdk = 36 — 代码可以编译，但在 API 35 的设备上，如果不检查就直接调用此方法将导致错误。

compileSdkVersion 从通过 Android Studio 中的 SDK Manager 安装的 Android SDK Platform 加载。每个 API Level 都有自己的平台：android-21、android-29、android-34、android-35、android-36。平台包含 android.jar — Kotlin/Java 编译器使用的类、方法和常量的集合。如果平台未安装，Gradle 将在第一次构建时通过 sdkmanager 自动下载它。

AGP（Android Gradle 插件）8.7+ 版本建议在 Kotlin DSL 中通过 compileSdk = 36 将 compileSdk 指定为整数，无需 android- 前缀。compileSdk 还可以通过 Groovy DSL 中的 compileSdkVersion 36 或通过 compileSdkPreview 为 SDK 的预览版本（开发者预览版）指定。compileSdkPreview 用于在正式发布前测试即将推出的 API Level。

// build.gradle.kts — compileSdkVersion 配置
android {
    namespace = "com.example.myapp"

    // compileSdk = 36 — 最新的稳定 API Level (Android 16)
    compileSdk = 36

    defaultConfig {
        applicationId = "com.example.myapp"
        minSdk = 26
        targetSdk = 36
        versionCode = 1
        versionName = "1.0.0"
    }
}

// 或者：为预览版使用 compileSdkPreview
// compileSdkPreview = "Baklava"

在示例中，compileSdk = 36 提供对所有 Android 16 (Baklava) API 的访问。Android SDK Platform 36 必须安装在 SDK Manager 中。名为 "Baklava" 的 compileSdkPreview 可用于在平台正式发布前测试不稳定的 API。发布后，预览版将替换为稳定的 compileSdk = 36。

compileSdkVersion vs targetSdkVersion vs minSdkVersion

build.gradle 中的三个 API Level 参数 — compileSdkVersion、targetSdkVersion 和 minSdkVersion — 经常被混淆。每个参数负责兼容性的不同方面，它们的值应根据 compileSdk >= targetSdk >= minSdk 规则进行协调。minSdk — 最低下限：低于此版本的设备将无法看到应用程序。targetSdk — 测试点：behavioral changes 会启用到此级别。compileSdk — 上限：高于此级别的 API 对编译器不可用。

关键实践规则：compileSdk 可以在无需在设备上进行任何测试的情况下提高。这是一个安全的操作，只给编译器提供新版本的 android.jar。唯一风险是 — 可能在新版本平台中被移除的已弃用 API，但这在编译阶段就能发现并轻松修复。相反，提高 targetSdk 则需要完整的 QA 周期。

为什么 compileSdk 可以高于 targetSdk？假设 Android 16（API 36）发布了新 API，您想在代码中使用它们，但尚未测试 API 36 的 behavioral changes。您设置 compileSdk = 36（新 API 可用），targetSdk = 35（API 36 的 behavioral changes 关闭）。代码将编译，会在 SDK_INT 检查下使用新方法，而 API 36 的 behavioral changes 不会破坏应用程序，因为 targetSdk = 35。

正确组合示例

compileSdk = 36, targetSdk = 36, minSdk = 26 — 与最新 API 和 behavioral changes 完全兼容，覆盖 85% 的设备。compileSdk = 36, targetSdk = 34, minSdk = 26 — 新 API 可用，behavioral changes 仅到 API 34。compileSdk = 35, targetSdk = 36 — 不正确：compileSdk 低于 targetSdk，API 36 不可用，尽管 behavioral changes 36 处于活动状态。

如何更新 compileSdkVersion：分步指南

更新 compileSdkVersion — Android 项目中最简单、最安全的操作之一。与 targetSdk 不同，它不需要长时间的 behavioural changes 测试。但是，需要执行几个步骤来避免编译错误和弃用警告。

步骤 1 — 通过 Android Studio 中的 SDK Manager 安装新平台：Tools → SDK Manager → SDK Platforms → 选择新的 API Level。如果您不安装平台，Gradle 将尝试自动下载它，但这可能会减慢首次构建的速度。步骤 2 — 将 build.gradle 中的 compileSdk 更改为新值。步骤 3 — 执行构建（Build → Make Project）并修复编译错误。

步骤 4 — 检查已弃用的 API。提高 compileSdk 后，某些方法可能带有 @Deprecated 标记和 "removed in API X" 注释。Android Studio 会用删除线突出显示它们并发出警告。用新的替代品替换已弃用的调用。如果替代品需要高于 minSdk 的 API Level，请添加运行时检查。步骤 5 — 检查 dependencies：某些库可能需要特定版本的 compileSdk。AGP 8.7+ 推荐使用 compileSdk = 36。

// 提高 compileSdk 后：替换已弃用的 API
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.os.Process
import android.app.ActivityManager

class CompileSdkMigration {

    // 之前：已弃用的方法（可能在新 API 中被移除）
    @Suppress("DEPRECATION")
    fun getMemoryClassOld(context: android.content.Context): Int {
        val am = context.getSystemService(
            android.content.Context.ACTIVITY_SERVICE
        ) as ActivityManager
        return am.memoryClass  // 可能在 API 36 中被弃用
    }

    // 之后：新的替代方案（如果可用）
    fun getMemoryClassNew(context: android.content.Context): Int {
        if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // 来自 compileSdk 36 的新 API
            val am = context.getSystemService(
                android.content.Context.ACTIVITY_SERVICE
            ) as ActivityManager
            return am.getMemoryClassSafe()  // 新 API 示例
        }
        @Suppress("DEPRECATION")
        return context.getSystemService(
            android.content.Context.ACTIVITY_SERVICE
        ) as ActivityManager
            .memoryClass
    }
}

CompileSdkMigration 类展示了正确的迁移模式。旧的 memoryClass 方法可能在新 API 中被移除 — 编译器将报错。新的替代品 getMemoryClassSafe 仅在 API 36+ 上可用，因此在 SDK_INT >= BAKLAVA 检查下调用。对于旧设备，使用带有 @Suppress("DEPRECATION") 的回退。

使用新 API：条件检查和回退

新 API，通过提高 compileSdkVersion 而可用，如果 minSdkVersion 低于此 API Level，则不能直接调用。没有运行时检查，应用程序将在旧设备上崩溃，出现 AbstractMethodError、NoSuchMethodError 或 VerifyError。主要保护机制 — 检查 Build.VERSION.SDK_INT，仅在 API Level 足够时调用新 API，并为旧版本提供回退。

AndroidX 提供了许多新 API 的向后移植，即使在较低的 compileSdk 下也能使用现代方法。例如，来自 androidx.activity:activity-ktx:1.9.3 的 Activity Result API 适用于从 API 14 开始的所有 Android 版本。来自 AndroidX 的 NotificationCompat 允许在旧 API 上使用现代通知。PhotoPicker 从 API 34+ 开始通过 ActivityResultContracts.PickVisualMedia 可用。

// 使用 compileSdk 36 和 minSdk 26 安全调用新 API
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.graphics.Color

class NewApiHelper {

    // API 36+：处理颜色的新方法
    fun formatColor(colorInt: Int): String {
        if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // 来自 compileSdk 36 的新 API — 需要 API 36+
            return Color.toArgbHexString(colorInt)
        }
        // 回退：为旧 API 手动格式化
        return String.format(
            "#%08X", (0xFFFFFFFF toLong() and colorInt.toLong())
        )
    }

    // AndroidX：无需向后移植 — SDK_INT 检查
    fun isEdgeToEdgeAvailable(): Boolean {
        return VERSION.SDK_INT >= VERSION_CODES.VANILLA_ICE_CREAM
    }
}

// 在 Activity 中使用
class ColorActivity : android.app.Activity() {
    override fun onCreate(savedInstanceState: android.os.Bundle?) {
        super.onCreate(savedInstanceState)
        val helper = NewApiHelper()
        val colorStr = helper.formatColor(0xFF6200EE)
        println("Color: $colorStr")
    }
}

NewApiHelper 类演示了安全调用新 API Color.toArgbHexString（假设的 API 36），并为旧版本提供回退格式化。关键原则：compileSdk 提供了在代码中调用新方法的能力，但运行时 SDK_INT 检查保护旧设备免于崩溃。没有 SDK_INT 检查，具有 minSdk 26 和 compileSdk 36 的应用程序将在 Android 8-15 上崩溃。

AGP（Android Gradle 插件）和 compileSdkVersion

Android Gradle 插件（AGP）— 构建 Android 应用程序的主要工具。每个 AGP 版本支持一定范围的 compileSdkVersion。AGP 8.7.x（于 2026 年发布）需要 compileSdk >= 34 并推荐 compileSdk = 36。AGP 8.5.x 支持 compileSdk 33-35。如果 compileSdk 低于 AGP 的最低要求，构建将以错误结束："The SDK platform (X) is not supported by this version of the Android Gradle Plugin"。

NDK（原生开发工具包）也与 compileSdkVersion 相关联。如果项目通过 NDK 使用 C/C++ 原生代码，compileSdk 决定了头文件和库的版本。NDK r27+ 推荐使用 compileSdk 36。对于包含 .so 文件的库，compileSdk 通过 Application.mk 中的 APP_MIN_SDK_VERSION 影响原生代码的最低 API Level。

Gradle（7.6+）和 Kotlin（2.0+）也会影响与 compileSdk 的兼容性。AGP 8.7+ 需要 Gradle 8.9+ 和 Kotlin 2.0+。在提高 compileSdk 时，建议将 AGP、Gradle 和 Kotlin 更新到最新的稳定版本。请查看官方的 Android Gradle Plugin 兼容性表。

提高 compileSdk 时的典型问题

提高 compileSdkVersion 时的问题分为三类：compilation errors、deprecated warnings 和 runtime incompatibilities。Compilation errors — 方法已从 API 中移除，代码无法编译。Deprecated warnings — 方法标记为 @Deprecated，代码可以编译但有警告。Runtime incompatibilities — 新 API 对特定功能是必需的，当设备上的 API Level 不足时会导致错误。

第一个典型问题 — "Cannot resolve symbol X"。这意味着在新版 SDK 中，某个类或方法已从公共 API 中移除。解决方案：在新平台上寻找替代方案或使用 AndroidX 等效类。例如，AsyncTaskLoader 类在 API 28 中已弃用，并在较新版本中从公共 API 中移除。替代方案 — Kotlin Coroutines 或 WorkManager。

第二个问题 — 方法签名的变更。在新版 API 中，方法可能改变了参数的数量或类型。Kotlin/Java 编译器会报错 "None of the following functions can be called with the arguments supplied"。解决方案：将方法调用更新为新签名，或添加 SDK_INT 检查，对旧设备使用旧签名调用。

// 解决提高 compileSdk 时的问题
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.content.pm.PackageManager

class CompileSdkProblemFixer {

    // 问题：hasSystemFeature 方法在 API 36 中更改了签名
    fun hasCamera(pm: PackageManager): Boolean {
        return if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // 新签名：hasSystemFeature(String, FeatureType)
            pm.hasSystemFeature(
                PackageManager.FEATURE_CAMERA,
                PackageManager.FEATURE_TYPE_BACK
            )
        } else {
            // 旧签名：hasSystemFeature(String)
            @Suppress("DEPRECATION")
            pm.hasSystemFeature(PackageManager.FEATURE_CAMERA)
        }
    }

    // 问题：类已移除，使用 AndroidX 等效类
    fun loadFragment(manager: androidx.fragment.app.FragmentManager) {
        // 代替 android.app.FragmentManager（已移除）使用
        // androidx.fragment.app.FragmentManager
        val fragment = CustomFragment()
        manager.beginTransaction()
            .replace(android.R.id.content, fragment)
            .commit()
    }
}

CompileSdkProblemFixer 类解决了典型问题：更改后的 hasSystemFeature 签名（API 36 中的假设性更改）通过 SDK_INT 检查并调用正确版本的方法来处理。已移除的 android.app.FragmentManager 类被 AndroidX 等效类替换。对于没有替代方案的旧调用，使用 @Suppress("DEPRECATION") 并附上保留原因的注释。