iOS应用终止状态下_firebaseMessagingBackgroundHandler未触发及CallKit通知问题

核心原因 #

iOS 系统对普通推送（包括FCM）有严格限制：当应用被完全清除（从后台划掉）或处于分离模式时，普通推送无法唤醒应用进程，自然无法执行 FlutterCallkitIncoming.showCallkitIncoming() 方法。而 CallKit 在 iOS 上必须依赖VoIP 推送才能在应用被杀死时唤醒进程并触发来电界面。

具体解决步骤 #

1. 切换为 VoIP 推送替代普通 FCM 通知 #

• 普通 FCM 推送无法满足 iOS 后台/杀死状态下的唤醒需求，必须使用 Apple 原生的 VoIP 推送服务，配合 Firebase 的 VoIP 推送集成。

2. 配置 iOS 开发者证书与权限 #

• 登录 Apple 开发者后台，为你的 App ID 开启 Push Notifications 和 Voice over IP 服务。
• 生成并下载 VoIP 推送证书（.p12 格式），上传到 Firebase 控制台的「项目设置 → 云消息传递 → iOS 应用」中。
• 在 Info.plist 中添加 VoIP 相关配置：

  <key>UIBackgroundModes</key>
  <array>
      <string>voip</string>
  </array>
  

3. 集成 VoIP 推送处理插件 #

使用专门的 Flutter VoIP 推送插件（比如 flutter_voip_push_notification）来处理 VoIP 推送的回调，因为 firebase_messaging 不直接支持 VoIP 推送的唤醒逻辑：

• 添加依赖到 pubspec.yaml：

  flutter_voip_push_notification: ^latest_version
  

• 在 AppDelegate 中配置 VoIP 推送监听（Objective-C/Swift），确保推送到达时能唤醒 Flutter 引擎并触发回调。
• 在 Flutter 层注册 VoIP 推送回调，在回调中直接调用 FlutterCallkitIncoming.showCallkitIncoming()，示例代码：

  void initVoipPush() {
    FlutterVoipPushNotification.instance.onTokenRefresh.listen((token) {
      // 将VoIP令牌上传到你的服务器，用于后续推送
    });
  
    FlutterVoipPushNotification.instance.onMessage.listen((message) {
      // 解析推送消息中的来电参数
      final callKitParams = CallKitParams(
        id: message['callId'],
        nameCaller: message['callerName'],
        handle: message['callerNumber'],
        type: 0,
      );
      FlutterCallkitIncoming.showCallkitIncoming(callKitParams);
    });
  }
  

4. 确保 CallKit 权限正确请求 #

在应用启动时，主动请求 CallKit 和通知权限：

void requestPermissions() async {
  await FlutterCallkitIncoming.requestPermissions();
  await FirebaseMessaging.instance.requestPermission();
}

5. 正确发送 VoIP 推送 #

• 普通 FCM 控制台无法发送 VoIP 推送，需要通过 Apple APNs 的 VoIP 接口发送，或者使用后端服务调用 Firebase 的 VoIP 推送 API。
• 推送 payload 必须符合 VoIP 格式要求，示例：

  {
    "aps": {
      "alert": {
        "title": "来电",
        "body": "张三正在呼叫你"
      },
      "content-available": 1,
      "category": "INCOMING_CALL"
    },
    "callId": "unique-call-id",
    "callerName": "张三",
    "callerNumber": "138xxxxxxx"
  }
  

注意事项 #

• iOS 13+ 要求 VoIP 推送必须在收到后 30 秒内展示 CallKit 界面，否则系统会杀死进程。
• 测试 VoIP 推送时，不能使用模拟器，必须用真实设备。
• 如果使用第三方推送服务，确保其支持 VoIP 推送的转发。

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