Xamarin Forms Android Release Mode下OneSignal通知不显示且报类找不到错误

Debug模式下Xamarin Android默认不会启用激进的代码剥离，所有OneSignal SDK的组件都会完整打包进APK，所以通知接收、类加载都正常。
但Release模式下默认启用链接器（Linker）和R8代码混淆机制，会自动移除它判断“没有被代码直接静态调用”的类。而日志里报错的三个类：

• com.onesignal.GcmBroadcastReceiver
• com.google.firebase.iid.FirebaseInstanceIdReceiver
• com.onesignal.RestoreKickoffJobService
  全是靠Android系统的组件管理器通过类名反射直接实例化的——业务代码里根本不会主动调用new创建这些类，所以链接器直接把它们当成无用代码从APK里剥掉了。
  Android One设备本身是近原生系统，没有定制ROM的类预加载、缺失类兜底缓存机制，所以一旦系统尝试启动这些被剥离的组件，就直接触发ClassNotFoundException崩溃，同时推送通道因为没有对应的Receiver和Service驻留，自然完全收不到通知。

1. 添加类保留规则，阻止链接器剥离OneSignal相关组件 #

有两种等效实现方式，选一种即可：

• 在Android项目根目录新建KeepRules.xml文件，将文件属性设置为“AndroidLinkDescription”，内容写入：

<linker>
  <!-- 保留OneSignal所有组件类 -->
  <assembly fullname="OneSignal">
    <type fullname="*" />
  </assembly>
  <!-- 保留Firebase推送相关类 -->
  <assembly fullname="Xamarin.Firebase.Messaging">
    <type fullname="*" />
  </assembly>
</linker>

• 或者直接在项目的AssemblyInfo.cs文件里加强制保留特性，无需额外配置文件：

using Android.Runtime;

// 强制保留日志报错的三个核心类
[assembly: Preserve(typeof(com.onesignal.GcmBroadcastReceiver), AllMembers = true)]
[assembly: Preserve(typeof(com.google.firebase.iid.FirebaseInstanceIdReceiver), AllMembers = true)]
[assembly: Preserve(typeof(com.onesignal.RestoreKickoffJobService), AllMembers = true)]
// 整集OneSignal、Firebase程序集不被剥离
[assembly: Preserve(typeof(OneSignal.OneSignalPlatform), AllMembers = true)]

2. 调整Release模式的链接器级别 #

打开Android项目的属性面板 → 找到Android Build → 切换到Release配置页：

• 把链接器行为从默认的“链接所有程序集”调整为仅链接框架程序集。这个模式下链接器只会清理Xamarin自带SDK里未被引用的代码，不会随意移除第三方Nuget包的组件，从根源上减少误删问题。
• 如果因为包体大小限制必须用“链接所有程序集”模式，就必须配合第一步写的保留规则，不然一定会出现类被剥离的问题。

3. 调整R8混淆规则 #

Release模式默认开启的R8代码混淆会把类名改成无意义的短字符串（比如把com.onesignal.GcmBroadcastReceiver改成a.b.c），和AndroidManifest里注册的组件类名完全对不上，也会触发类找不到的错误。
打开Android项目根目录的proguard-rules.pro文件，追加保留规则：

# 禁止混淆OneSignal、Firebase相关类
-keep class com.onesignal.** { *; }
-keep class com.google.firebase.** { *; }
-keep class com.google.android.gms.** { *; }

同时在项目属性里确认R8的优化级别不要开最高级的全量优化，不然即使写了keep规则也可能被优化掉反射调用的逻辑。

4. 适配Android One设备的特殊管控逻辑 #

Android One设备的系统权限管控比定制ROM更严格：

• 检查应用是否被允许后台自启动，OneSignal的长连接Service需要后台保活能力，必要时可以在应用首次启动时引导用户给应用开放自启动权限。
• 确认应用的通知渠道在Android 13+以上系统已经被用户手动授权，原生系统不会默认给应用开放通知权限。

每次修改完配置后，一定要先删掉项目的bin和obj文件夹，清理所有旧的构建缓存，重新编译Release包安装到设备上。观察logcat日志，如果不再出现之前的三个ClassNotFoundException、InstantiationException报错，再测试推送接收功能，即可正常收到通知。

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