如何使用FCM创建iOS富文本通知Payload？适配问题求助

阿华AIGC实验室

2026-5-28

解决FCM推送iOS富文本通知时mutable-content和category字段不生效的问题

你遇到的核心问题是FCM推送iOS时，APS相关配置字段没有放在正确的层级结构里。FCM和原生APNS的Payload映射规则不一样，直接照搬APNS结构或者把字段放在根节点/gcm.notification下，iOS端都无法正确解析到aps字典中。

正确的FCM Payload配置方式

要让mutable-content和category正确出现在iOS接收的aps字段里，你需要把完整的APS配置嵌套在apns.payload层级下，自定义字段（比如image_url）可以放在data节点中（避免和FCM系统字段冲突）。

示例Payload如下：

{
  "apns": {
    "payload": {
      "aps": {
        "alert": {
          "title": "Product Notification",
          "body": "new product notification message2018-05-24 00:00:00"
        },
        "badge": 1,
        "sound": "default",
        "mutable-content": 1,
        "category": "defaultCategory",
        "content-available": 1
      },
      "image_url": "https://example.com/r/u/rustyredsmall.jpg"
    }
  },
  "data": {
    "type_id": "XMH677878912-L-Blue",
    "type": "Product"
  }
}

为什么之前的配置无效？

你之前尝试的方案踩了两个常见的映射误区：

mutable_content（下划线格式）是FCM的旧字段，它不会自动转换为APNS要求的mutable-content（中划线格式），必须直接在aps字典里定义mutable-content: 1
click_action是FCM用来指定通知点击跳转动作的字段，和APNS的category（通知分类）不是同一个概念，完全不能替代
你收到的Payload里，gcm.notification.category和根节点的mutable_content都不在APS的解析范围内，所以iOS无法触发富文本扩展和分类通知逻辑

验证方法

推送后，在iOS的通知扩展或AppDelegate中打印userInfo，正确的接收结果应该是：

{
  "aps": {
    "alert": {
      "body": "new product notification message2018-05-24 00:00:00",
      "title": "Product Notification"
    },
    "badge": 1,
    "sound": "default",
    "mutable-content": 1,
    "category": "defaultCategory",
    "content-available": 1
  },
  "image_url": "https://example.com/r/u/rustyredsmall.jpg",
  "type_id": "XMH677878912-L-Blue",
  "type": "Product",
  "gcm.message_id": "0:xxxxxx..."
}

只要aps字典里包含mutable-content和category，富文本通知和分类动作就能正常工作了。

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