Android 启用核心库脱糖解决 flutter_local_notifications 依赖问题

问题描述

在使用 Flutter 开发 Android 应用时，当项目中包含 flutter_local_notifications 插件后构建失败，错误信息显示：

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':app:checkDebugAarMetadata'.
> A failure occurred while executing com.android.build.gradle.internal.tasks.CheckAarMetadataWorkAction
   > An issue was found when checking AAR metadata:

       1.  Dependency ':flutter_local_notifications' requires core library desugaring to be enabled
           for :app.

           See https://developer.android.com/studio/write/java8-support.html for more
           details.

此错误表明 flutter_local_notifications 插件依赖 核心库脱糖（Core Library Desugaring）功能。核心库脱糖允许在低版本 Android 设备上使用 Java 8+ 的新语言特性（如新的时间 API、流 API 等），而无需提升 minSdkVersion。

解决方案

核心修复步骤

在项目的 app/build.gradle 文件中进行以下修改：

1. 开启核心库脱糖功能 在 android > compileOptions 区域中添加 coreLibraryDesugaringEnabled true

2. 添加脱糖库依赖 在 dependencies 区域中添加对应版本的脱糖库

语法说明

项目使用 Groovy DSL (build.gradle) 或 Kotlin DSL (build.gradle.kts)，配置语法有所不同

1. Groovy DSL 配置示例 (推荐)

适用于标准的 build.gradle 文件（使用 Groovy 语法）:

android {
    compileOptions {
        // ✅ 启用核心库脱糖功能
        coreLibraryDesugaringEnabled true
        
        // 设置 Java 版本（1.8 或更高）
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

dependencies {
    // ✅ 添加核心库脱糖依赖（根据 AGP 版本选择）
    // AGP 7.4+ 使用 2.x 版本
    coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:2.0.4'
    // 旧版本 AGP 兼容
    // coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:1.2.2'
}

版本选择

• Android Gradle Plugin (AGP) 7.4+：使用 desugar_jdk_libs:2.x.x
• Android Gradle Plugin (AGP) 7.3.x：使用 desugar_jdk_libs:1.2.3
• Android Gradle Plugin (AGP) 4.0-7.2.x：使用 desugar_jdk_libs:1.1.9

2. Kotlin DSL 配置示例

适用于 build.gradle.kts 文件（使用 Kotlin 语法）:

android {
    compileOptions {
        // ✅ 启用核心库脱糖功能 (Kotlin DSL 写法)
        isCoreLibraryDesugaringEnabled = true
        
        // 设置 Java 版本
        sourceCompatibility = JavaVersion.VERSION_11
        targetCompatibility = JavaVersion.VERSION_11
    }
}

dependencies {
    // ✅ 添加脱糖库依赖
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.0.4")
}

完整配置参考

以下是一个完整的 app/build.gradle 配置示例，包含所有必要的修复：

android {
    namespace "com.example.app"
    compileSdkVersion 34
    ndkVersion "25.1.8937393"

    compileOptions {
        // ✅ 必要配置：启用核心库脱糖
        coreLibraryDesugaringEnabled true
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }

    kotlinOptions {
        jvmTarget = '1.8'
    }

    sourceSets {
        main.java.srcDirs += 'src/main/kotlin'
    }

    defaultConfig {
        applicationId "com.example.app"
        minSdkVersion 21
        // ✅ 如 minSdk ≤ 20 需要开启 MultiDex
        multiDexEnabled true
        targetSdkVersion 34
        versionCode 1
        versionName "1.0"
    }

    buildTypes {
        release {
            signingConfig signingConfigs.debug
        }
    }
}

dependencies {
    implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk7:$kotlin_version"
    // ✅ 添加脱糖库依赖（使用最新兼容版本）
    coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:2.0.4'
}

后续操作

应用以上修改后，需要执行以下步骤完成修复：

# 清理构建缓存
flutter clean

# 重新获取项目依赖
flutter pub get

# 重新运行项目
flutter run

技术原理

核心库脱糖的核心原理是通过依赖 desugar_jdk_libs 库实现：

1. 编译期转换：将 Java 8+ 的新 API 调用转换为兼容的低版本 API
2. 代码重写：自动重写使用了新语言特性的代码
3. 运行时支持：在应用启动时加载兼容层库

这样可以在保持较低 minSdkVersion 的同时，享用在较新 Java 版本中添加的平台功能，特别是对于 flutter_local_notifications 这种使用新版时间 API 的插件至关重要。

注意事项

1. JDK 兼容性：建议升级 Android Studio 使用的 JDK 到 11 或更高版本
2. Gradle 版本：确保 gradle-wrapper.properties 中的 Gradle 版本 ≥ 7.4

distributionUrl=https\://services.gradle.org/distributions/gradle-8.4-bin.zip

3. AGP 版本：在 android/build.gradle 中升级 Android Gradle Plugin：

classpath 'com.android.tools.build:gradle:8.3.0'

通过这些配置调整，即可顺利解决依赖 flutter_local_notifications 时出现的核心库脱糖相关编译错误，确保应用在新旧 Android 设备上正常工作。