Flutter Android Release构建中OneSignal初始化失败，抛出MissingPluginException异常

阿华AIGC实验室

2026-3-31

我之前也碰到过这种只在Release构建才出现的诡异问题，大概率是代码混淆或者Flutter Release模式的优化规则把OneSignal的原生实现给“吃掉”了，下面给你整理几个经过验证的排查和解决思路：

问题核心总结

异常表现：Android Release构建启动时连续抛出MissingPluginException，提示OneSignal的MethodChannel找不到对应实现；Debug构建、iOS构建完全正常
环境版本：OneSignal 5.3.4、Flutter 3.29.2
复现步骤：
1. 将OneSignal升级至5.3.4
2. 在Flutter 3.29.2项目的main.dart中初始化OneSignal
3. 构建并运行Android Release版本

解决方案逐个试

1. 必须添加OneSignal的R8混淆规则

Release模式下R8混淆会默认移除未被识别的原生代码，OneSignal的核心实现很容易被误删，你需要在android/app/proguard-rules.pro中添加以下规则：

# 保留OneSignal所有类和方法不被混淆
-keep class com.onesignal.** { *; }
-keep class com.onesignal.core.** { *; }
-keep class com.onesignal.notifications.** { *; }
-keep class com.onesignal.inAppMessages.** { *; }
-keep class com.onesignal.user.** { *; }
-keep class com.onesignal.pushSubscription.** { *; }

同时确保android/app/build.gradle的Release构建块正确启用混淆并关联规则文件：

buildTypes {
    release {
        minifyEnabled true
        shrinkResources true
        proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
    }
}

2. 清理所有缓存后重新构建

有时候旧的构建缓存会导致Release模式异常，执行以下命令彻底清理后再打包：

# 清理Flutter缓存
flutter clean
# 清理Android Gradle缓存
cd android && ./gradlew clean
# 回到项目根目录重新构建Release APK
cd .. && flutter build apk --release

3. 手动在原生层确认OneSignal初始化

可以暂时在Android原生的MainActivity中手动初始化OneSignal，排除Dart端的干扰，验证原生实现是否正常：
如果是Kotlin版本的MainActivity.kt：

import com.onesignal.OneSignal
import io.flutter.embedding.android.FlutterActivity

class MainActivity : FlutterActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // 手动初始化OneSignal
        OneSignal.initWithContext(this)
        OneSignal.setAppId("你的OneSignal AppID")
    }
}

注意：测试时可以暂时注释Dart端的OneSignal.initialize()，避免重复初始化。如果原生层初始化后不再抛异常，说明是Dart端和原生端的关联被混淆打断了，回到第一步检查混淆规则是否生效。

4. 检查版本兼容性降级/升级测试

虽然你用的是官方标注兼容的版本，但偶尔会有版本适配小问题：

可以尝试降级OneSignal到5.3.3，或者升级到最新稳定版
确认Flutter 3.29.2和OneSignal 5.x的兼容性（官方文档显示是兼容的，但可以用最小测试项目验证）

5. 禁用Flutter的Release模式优化（临时测试用）

如果以上方法都不行，可以临时关闭Flutter的Release优化来验证：
在android/app/build.gradle中添加：

android {
    buildTypes {
        release {
            // 临时关闭优化，仅用于测试
            minifyEnabled false
            shrinkResources false
        }
    }
}

如果关闭后异常消失，说明确实是混淆/优化导致的，回到第一步仔细检查混淆规则。