如何在Cordova FCM中使用Notification Service Extension

适用场景：Ionic/Cordova 项目集成 FCM 推送，需要实现 iOS 富通知推送、送达统计上报能力。
前置依赖确认：

• Xcode 版本 ≥ 12.0
• 项目 iOS 部署目标 ≥ 10.0
• 已安装官方维护的 Cordova FCM 插件，项目Firebase配置文件（GoogleService-Info.plist）已正确放入主工程

操作步骤 #

1. 创建Extension靶标 #

• 进入项目根目录执行cordova prepare ios生成完整iOS工程
• 打开platforms/ios目录下的.xcworkspace文件（注意不要打开.xcodeproj文件，否则CocoaPods依赖会加载失败）
• 在Xcode左侧选中工程根节点，点击顶部菜单 File > New > Target，在弹出的模板列表里选Notification Service Extension，点击Next
• 填写Extension产品名（例如FCMServiceExt），开发语言选Swift/Objective-C均可，Bundle ID必须和主App Bundle ID同前缀，例如主App ID为com.demo.app，Extension ID设为com.demo.app.FCMServiceExt，禁止和主App ID重复
• 弹出是否激活Extension Scheme的提示时，直接选Activate
• 选中刚创建的Extension靶标，打开Build Settings页签，找到iOS Deployment Target项，将版本号改成和主App完全一致，不要保留模板默认的高版本，否则低版本iOS系统无法加载Extension

2. 配置签名与能力 #

• 选中主App靶标，切到Signing & Capabilities页签，确认已开启两项能力：
  • Push Notifications
  • Background Modes 下勾选 Remote notifications
• 选中Extension靶标，切到Signing & Capabilities页签，开启Push Notifications能力，签名选择和主App一致的开发团队，确保证书状态正常无报错

3. 编写Extension核心逻辑 #

如果创建Extension时选了Swift语言，打开自动生成的NotificationService.swift文件，全量替换为以下代码：

import UserNotifications
import FirebaseMessaging

class NotificationService: UNNotificationServiceExtension {
    var contentHandler: ((UNNotificationContent) -> Void)?
    var bestAttemptContent: UNMutableNotificationContent?

    override func didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) {
        self.contentHandler = contentHandler
        bestAttemptContent = request.content.mutableCopy() as? UNMutableNotificationContent
        guard let content = bestAttemptContent else {
            contentHandler(request.content)
            return
        }
        // FCM 官方扩展处理逻辑：自动解析富媒体、上报消息送达事件
        FIRMessagingExtensionHelper().populateNotificationContent(content, withContentHandler: contentHandler)
    }

    override func serviceExtensionTimeWillExpire() {
        // 处理超时兜底，返回当前已处理的最佳内容
        if let handler = contentHandler, let content = bestAttemptContent {
            handler(content)
        }
    }
}

如果选了Objective-C语言，对应替换NotificationService.m文件的代码即可，逻辑完全一致。

• 选中Extension靶标，打开Build Phases > Link Binary With Libraries，添加FirebaseMessaging.framework，将库的引用状态设为Optional，避免强制依赖导致加载报错

4. 持久化配置避免构建覆盖 #

Cordova每次执行build/prepare操作会重置iOS工程配置，需要做持久化处理：

• 如果Extension用Swift开发，先执行npm i cordova-plugin-add-swift-support --save安装Swift支持插件，OC开发可跳过
• 在项目config.xml的iOS平台配置块中添加Extension靶标的引用配置，确保后续构建不会自动删除Extension
• 重新执行cordova prepare ios，回到Xcode确认Extension靶标存在、签名配置正常即可

验证与常见问题排查 #

• 发推送时必须在APNs/FCM payload中添加mutable-content: 1字段，否则系统不会触发Extension逻辑
• 真机测试收推送，若富媒体（图片、音频、视频）正常展示、FCM后台送达统计有数据，说明集成成功
• 常见失效原因：Extension签名和主App不一致、Extension部署目标版本高于测试机系统版本、payload漏加mutable-content字段、FirebaseMessaging库未正确链接到Extension靶标、误引入第三方SDK的自定义Extension类导致逻辑冲突

最简实现不需要参考第三方推送服务商的自定义Extension逻辑，仅调用FCM官方提供的扩展处理方法即可，额外引入第三方代码反而容易产生冲突。

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