minSdkVersion：什么是minSdkVersion、如何选择最低Android版本

Android中什么是minSdkVersion？

minSdkVersion — build.gradle中的一个整数参数，用于设置安装应用程序所需的最低Android API级别。如果设备的API级别低于指定值，PackageManager会阻止安装，Google Play Store也会对这类设备隐藏该应用程序的搜索结果。minSdkVersion在构建阶段通过标签<uses-sdk android:minSdkVersion>写入AndroidManifest.xml，并在每次安装时进行检查。

minSdkVersion的值是受众覆盖范围与新API访问之间的折衷。minSdk越低，可以安装应用程序的设备就越多，尤其是在旧Android智能手机流行的发展中地区。minSdk越高，需要的向后兼容代码就越少，更多的现代API无需运行时检查即可使用。Android Jetpack和AndroidX库为许多新API提供了向后移植到旧Android版本的功能，从而可以在不损失功能的情况下选择更低的minSdk。

minSdkVersion影响开发的所有阶段：静态分析（lint使用minSdk进行警告）、依赖兼容性（库可能要求自己的minSdk）、测试（需要在具有minSdk的设备上测试）和Google Play Console（受众覆盖率基于minSdk计算）。更改minSdkVersion是项目配置中最重要的决定之一，因为它会影响代码、测试和用户群。

minSdkVersion在哪里指定

Build.gradle.kts（Kotlin DSL）— Android项目的现代标准。minSdk参数在模块级别的defaultConfig块中设置。该值可以针对不同的构建类型和产品变体进行覆盖，从而可以在不更改主要值的情况下在更低的API上进行测试。

// build.gradle.kts — minSdk的基本配置
android {
    namespace = "com.example.myapp"
    compileSdk = 36

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

    // 为不同flavor覆盖minSdk
    flavorDimensions += "tier"
    productFlavors {
        create("free") {
            minSdk = 26
        }
        create("premium") {
            minSdk = 26
        }
    }
}

在示例中，minSdk = 26对应Android 8.0 Oreo。这是2026年的流行值：根据Android Studio Distribution Dashboard，它仅排除了约15%的设备。compileSdk = 36提供对所有Android 16 API的访问，targetSdk = 36则启用最新版本的行为更改。对于调试构建，可以降低minSdk以在旧模拟器上进行测试。

如何选择minSdkVersion：因素和策略

选择minSdkVersion — 基于目标受众、API要求和库生态系统分析的战略决策。没有适用于所有项目的单一正确值。2026年，Android Studio推荐minSdk = 26（Android 8.0）作为新项目的基础级别，但对于B2B应用程序或企业解决方案，较低或较高的值也是可以接受的。

选择minSdkVersion的因素

第一个因素 — Distribution Dashboard。Android Studio基于Google Play的数据提供按API级别划分的活跃设备统计信息，每月更新。minSdkVersion应至少覆盖目标市场90-95%的活跃设备。对于受众在非洲和东南亚的国际应用程序，由于旧设备比例较高，minSdk应降低到21（Android 5.0）。

第二个因素 — 依赖要求。每个库都有自己的minSdkVersion在其清单中指定。如果库要求minSdk 29而应用程序要求minSdk 26，构建将失败并出现manifest merger错误。现代Google Play Services库具有minSdk 21，Firebase — minSdk 21，大多数Jetpack库 — minSdk 21或26，Compose BOM — minSdk 21。对于Compose，最低门槛是API 21。

第三个因素 — 必要的API。如果应用程序的关键功能需要仅从特定级别可用的API（例如PhotoPicker — API 34，Predicted Navigation — API 35），这可以证明提高minSdk是合理的。然而，更常用的是AndroidX向后移植（Activity Result API、NotificationCompat）和运行时检查的组合，以保持较低的minSdk。

逐步选择策略

步骤1：打开Android Studio，File → New Project，查看向导中推荐的minSdk。步骤2：在Android Studio中检查Distribution Dashboard（View → Tool Windows → App Inspection → Distribution Dashboard）。步骤3：分析项目的依赖关系 — 执行构建并解决manifest merger冲突。步骤4：评估哪些X级别的API实际上没有使用向后移植。步骤5：将minSdk设置为覆盖90%+目标受众并与所有依赖兼容的最小值。

设备覆盖率：API级别分布（2026年）

设备分布按API级别 — 一个每季度变化的动态指标。根据2026年6月的Android Studio Distribution Dashboard，约85%的活跃Android设备运行在API 26（Android 8.0）及更高版本上，72%运行在API 29（Android 10）及更高版本上，55%运行在API 31（Android 12）及更高版本上。中国市场由于许多华为设备缺少Google Play Services而有自己的统计数据。

GMS设备（Google Mobile Services）更新更快：由于Google Play对制造商的强制性要求，其API 31+的份额达到68%。非GMS设备（华为、荣耀、一些中国品牌）具有更旧的分布：其API 31+的份额约为35%。如果应用程序面向国际市场，请依赖全球统计数据。如果面向中国市场 — 请考虑非GMS细分市场。

结论：对于国际应用程序，minSdk 26以最小的向后兼容成本覆盖了85%的设备。对于受众在发展中国家的应用程序，minSdk 21（97%覆盖率）是合理的，但需要更多的代码来处理旧版API。对于具有受控设备群的企业应用程序，可以设置minSdk 31并完全摆脱回退代码。

向后兼容性：AndroidX、lint和@RequiresApi

向后兼容性 — 低minSdkVersion下的主要困难。AndroidX（以前是Support Library）为现代API提供向后移植到旧Android版本的功能：用于Material Design的AppCompatActivity、FragmentManager、Loader、NotificationCompat、PreferenceFragmentCompat以及数十个其他组件。使用AndroidX等效组件代替原生API — 迈向兼容性的第一步。

lint（Android Studio的静态分析器）扫描代码以查找高于minSdkVersion的API调用。如果方法用@RequiresApi标记了高于minSdk的API级别并在没有检查的情况下被调用，lint会突出显示错误。要抑制警告，请在方法上使用@SuppressLint("NewApi")注释，或在整个函数上使用@RequiresApi(Build.VERSION_CODES.TIRAMISU)。运行时检查通过Build.VERSION.SDK_INT — 在旧设备上安全调用新API的主要机制。

// 向后兼容性示例：PhotoPicker（API 34+）和回退
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import androidx.activity.result.contract.ActivityResultContracts
import androidx.appcompat.app.AppCompatActivity

class ImagePickerActivity : AppCompatActivity() {

    // Activity Result API（AndroidX）— 在任何API级别上工作
    private val pickImageLauncher = registerForActivityResult(
        ActivityResultContracts.GetContent()
    ) { uri ->
        uri?.let { displayImage(it) }
    }

    fun pickImage() {
        // PhotoPicker仅从API 34开始可用
        if (VERSION.SDK_INT >= VERSION_CODES.UPSIDE_DOWN_CAKE) {
            // 我们使用PhotoPicker（API 34+）
            val intent = android.provider.MediaStore
                .ACTION_PICK_IMAGES
            startActivityForResult(intent, 100)
        } else {
            // 回退：GetContent（适用于所有版本）
            pickImageLauncher.launch("image/*")
        }
    }

    @RequiresApi(VERSION_CODES.UPSIDE_DOWN_CAKE)
    fun usePhotoPickerOnly() {
        // 此方法不能在API上调用 < 34
        val intent = android.provider.MediaStore
            .ACTION_PICK_IMAGES
        startActivityForResult(intent, 100)
    }
}

ImagePickerActivity类展示了三个级别的向后兼容性。来自AndroidX的Activity Result API在所有API级别上工作，因此对于基本图像选择，minSdk不重要。PhotoPicker（ACTION_PICK_IMAGES）仅从API 34开始可用，并在SDK_INT检查下调用，回退到GetContent。usePhotoPickerOnly方法用@RequiresApi标记 — lint不允许在没有检查的情况下调用它。来自AndroidX的AppCompat自动将主题、片段和动画适配到操作系统版本。

库和模块中的minSdkVersion

库（AAR、JAR）也有在其清单中指定的minSdkVersion。连接库时，Gradle会检查兼容性：如果库的minSdk高于应用程序的minSdk，构建会失败并出现错误。对于公共库，建议指定尽可能低的minSdk（大多数情况下为21），以免限制用户。如果库要求API 29+，它会失去约28%的潜在用户。

多模块项目可以为不同模块设置不同的minSdkVersion。例如，:core:network模块可以有minSdk 26，而:feature:camera模块可以有minSdk 29（由于CameraX的特定要求）。Google Play要求主模块:app的minSdk低于或等于所有依赖模块的minSdk。在实践中，一个应用程序的所有模块通常具有相同的minSdk以简化维护。

// build.gradle.kts — 具有低minSdk的库模块
plugins {
    id("com.android.library")
    id("org.jetbrains.kotlin.android")
}

android {
    namespace = "com.example.mylibrary"
    compileSdk = 36

    defaultConfig {
        minSdk = 21  // 最低限度实现最大覆盖
        targetSdk = 36
    }
}

dependencies {
    // AndroidX Core — minSdk 21，添加向后移植
    implementation("androidx.core:core-ktx:1.15.0")
    implementation("androidx.appcompat:appcompat:1.7.0")
}

具有minSdk = 21的库模块与97%的设备兼容，并且不限制用户。如果库使用21以上的API，开发人员必须添加运行时检查或在相应方法上指定@RequiresApi。AndroidX Core KTX（minSdk 21）为Context、Bundle、Locale和其他系统类提供向后移植，使库能够保持较低的minSdk。

选择minSdkVersion时的常见错误

选择minSdk时的错误可能造成数千次安装或数周的额外开发。第一个常见错误 — 在没有分析Distribution Dashboard的情况下从项目模板复制minSdk。许多开发人员从Android Studio模板中保留了minSdk = 21，而实际上对于他们的受众，minSdk 26就足够了，并且会减少代码中SDK_INT检查的数量。

第二个错误 — minSdk过高而没有考虑市场。如果您为国际应用程序设置minSdk = 31（Android 12），您将失去约45%的设备。对于初创公司或面向大众的应用程序来说，这是一场灾难。在提高minSdk之前，请始终检查Distribution Dashboard，如果不确定，请在Google Play Console中使用A/B测试。

第三个错误 — 忽略依赖项的minSdk。在添加新库时，请在文档或POM文件中检查其minSdk。Firebase ML Kit需要minSdk 21，一些自定义相机库需要minSdk 29。如果manifest merger因新库而在生产环境中失败，修复可能需要数天时间。

// 示例：运行时检查API兼容性
fun checkFeatureAvailability(): Boolean {
    // 典型错误 — 未检查SDK_INT就调用API
    return when {
        VERSION.SDK_INT >= VERSION_CODES.UPSIDE_DOWN_CAKE -> {
            // API 34+ — 我们使用PhotoPicker
            true
        }
        VERSION.SDK_INT >= VERSION_CODES.Q -> {
            // API 29-33 — 我们使用MediaStore
            true
        }
        else -> {
            // API < 29 — 使用 ACTION_GET_CONTENT
            true
        }
    }
}

正确的API级别检查架构 — 使用覆盖从minSdk到compileSdk所有可能值的范围的when表达式。关键规则：每个X级别API的调用都必须受到VERSION.SDK_INT检查的保护，适用于所有API级别从minSdk到X的设备。lint有助于检测未检查的调用，但不能保证对动态代码的完全覆盖。