解决 "The minCompileSdk (31) specified in a dependency's AAR metadata" 错误

问题描述

当使用 Android Studio 构建项目时，您可能会遇到以下错误：

The minCompileSdk (31) specified in a dependency's AAR metadata (META-INF/com/android/build/gradle/aar-metadata.properties) is greater than this module's compileSdkVersion (android-30).
Dependency: androidx.core:core-ktx:1.7.0-alpha02.

这个错误表示项目的 compileSdkVersion (编译版本) 低于某个依赖库所需的最低编译版本要求。具体来说，您使用的依赖库（如 androidx.core:core-ktx:1.7.0-alpha02）需要至少 Android SDK 31 才能编译，但当前项目的编译版本设置为 30。

根本原因

从 2021 年 9 月开始，AndroidX 库的新版本（特别是 1.7.0-alpha02 及更高版本）开始要求使用 Android 12 (SDK 31) 作为最低编译版本。这通常发生在以下情况：

1. 使用了 + 通配符版本号（如 androidx.core:core-ktx:+），它会自动获取最新版本
2. 显式使用了需要 SDK 31 的库版本（如 1.7.0-alpha02、1.7.0-beta01）
3. 项目中的 compileSdkVersion 设置低于 31

解决方案

方法一：升级 compileSdkVersion（推荐）

最简单的解决方案是将项目的编译版本升级到 31：

android {
    compileSdk 31
    
    defaultConfig {
        targetSdk 31
        // 其他配置...
    }
    // 其他配置...
}

TIP

只需升级 compileSdkVersion 通常就足够了，无需更改 targetSdkVersion 或 minSdkVersion。这样可以保持与应用商店的兼容性。

方法二：固定依赖版本

如果您暂时无法升级到 SDK 31，可以将相关依赖库固定到兼容的旧版本：

dependencies {
    // 替换所有使用通配符的依赖
    implementation "androidx.core:core-ktx:1.6.0" // 而不是 "androidx.core:core-ktx:+"
    implementation "androidx.core:core:1.6.0"
    // 其他依赖...
}

方法三：强制使用特定版本

在项目的 build.gradle 文件中添加强制解析策略：

configurations.all {
    resolutionStrategy { 
        force 'androidx.core:core-ktx:1.6.0'
        // 对于 Java 项目使用：
        // force 'androidx.core:core:1.6.0'
    }
}

将这个配置块放在 android 块之前。

方法四：检查所有模块的依赖一致性

确保项目中所有模块使用的依赖版本一致：

// 在所有模块中使用相同版本的依赖
implementation "androidx.core:core-ktx:1.6.0"
implementation "androidx.lifecycle:lifecycle-livedata:2.3.1"
implementation "androidx.navigation:navigation-compose:2.4.0-alpha06"

WARNING

避免使用 + 通配符版本号，这会导致构建不可预测，特别是当新版本发布时。

常见问题排查

React Native 项目

React Native 项目可能需要特别处理：

// android/app/build.gradle
configurations.all {
    resolutionStrategy { 
        force 'androidx.core:core-ktx:1.6.0'
        force 'androidx.core:core:1.6.0'
    }
}

Jetpack Compose 导航

如果您使用 Jetpack Compose 导航，请确保使用兼容版本：

dependencies {
    // 使用兼容版本而非最新版本
    implementation "androidx.navigation:navigation-compose:2.4.0-alpha06"
}

最佳实践

1. 避免通配符版本：始终指定具体的依赖版本号
2. 定期更新 SDK：保持 compileSdkVersion 与最新稳定版同步
3. 检查依赖兼容性：添加新依赖时确认其版本要求
4. 统一依赖版本：确保项目中所有模块使用相同版本的依赖库

版本兼容性参考

以下是常见 AndroidX 库的兼容版本：

库名称	兼容版本 (SDK 30)	需要 SDK 31 的版本
androidx.core:core-ktx	1.6.0	1.7.0-alpha02+
androidx.core:core	1.6.0	1.7.0-alpha02+
androidx.lifecycle:lifecycle-livedata	2.3.1	2.4.0-beta01+
androidx.navigation:navigation-compose	2.4.0-alpha06	2.4.0-alpha07+

结论

解决 "minCompileSdk (31)" 错误的最直接方法是升级项目的 compileSdkVersion 到 31。如果暂时无法升级，可以通过固定依赖版本或强制使用兼容版本来解决。长期来看，建议保持开发环境与最新的 Android SDK 版本同步，以避免类似的兼容性问题。

INFO

Android 12 (SDK 31) 引入了许多新功能和改进，升级到最新 SDK 版本可以获得更好的开发体验和应用性能。