集成background_fetch后Flutter应用Release模式启动崩溃问题

问题概况 #

Debug模式下应用正常运行，使用background_fetch的HeadlessTask实现后台通知接收；但Release模式启动后瞬间崩溃，报错java.lang.NoSuchMethodError，移除所有background_fetch相关代码后Release模式恢复正常。

错误日志 #

E/AndroidRuntime(11236): Process: com.flutter.XXXX, PID: 11236 
E/AndroidRuntime(11236): java.lang.NoSuchMethodError: No direct method (Lf/D;IZ)V in class Lh/c; or its super classes (declaration of 'h.c' appears in /data/app/~~Qr5BA6lM0nskPezOqHo_KA==/com.flutter.XXXX-EiPQeFA-QgI0qeJnzT_akg==/base.apk)

核心原因 #

Release模式开启了代码混淆（minifyEnabled true）和资源压缩，但未配置ProGuard规则保护background_fetch的核心类与方法，导致R8编译器将插件必要的方法移除或混淆，引发找不到方法的运行时错误。

修复步骤 #

1. 启用ProGuard并添加专属保护规则 #

修改app/build.gradle中的release构建配置，启用ProGuard并指定规则文件：

buildTypes {
    release {
        signingConfig signingConfigs.debug
        minifyEnabled true
        shrinkResources true
        debuggable true
        useProguard true // 启用ProGuard
        proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
    }
}

在app/proguard-rules.pro文件中添加以下规则，保护background_fetch及Flutter插件相关类：

# 保护background_fetch插件的所有类与方法
-keep class com.transistorsoft.** { *; }
-dontwarn com.transistorsoft.**

# 保护Flutter核心插件相关类，避免JNI方法被混淆
-keep class io.flutter.plugin.common.** { *; }
-keep class io.flutter.** { *; }
-dontwarn io.flutter.**

2. 统一版本配置，解决依赖冲突 #

检查app/build.gradle中重复的版本配置，删除重复项：

android {
    // 删除重复的compileSdkVersion和targetSdkVersion，保留rootProject.ext中的配置
    compileSdkVersion rootProject.ext.compileSdkVersion
    ndkVersion flutter.ndkVersion

    defaultConfig {
        // ...
        targetSdkVersion rootProject.ext.targetSdkVersion
        // ...
    }
}

同时确保Kotlin版本与Gradle插件版本兼容：当前Gradle插件为7.1.2，建议将Kotlin版本调整为1.7.20（适配该插件版本），修改android/build.gradle：

buildscript {
    ext.kotlin_version = '1.7.20'
    // ...
}

3. 清理缓存并重新构建 #

执行以下命令彻底清理项目缓存后构建Release包：

flutter clean
flutter build apk --release

额外验证点 #

• 确认AndroidManifest.xml已按background_fetch官方要求配置必要的权限与组件
• 检查pubspec.yaml中background_fetch的版本为最新稳定版，避免版本兼容问题

内容的提问来源于stack exchange，提问作者Selim Sayeh