Firebase Cloud Messaging：为APN加声音及APN HTTP v1 API优先级配置问题

要给APN通知配置声音，核心是在推送的payload里通过apns字段嵌套的aps对象指定sound参数，具体分两种常用场景：

• 使用FCM HTTP v1 API发送时
  直接构造包含声音配置的请求体即可，示例如下：

  {
    "message": {
      "token": "你的iOS设备推送令牌",
      "apns": {
        "payload": {
          "aps": {
            "sound": "default" // 用系统默认声音，或自定义音频文件名，比如"my_custom_sound.wav"
          }
        }
      },
      "notification": {
        "title": "测试通知",
        "body": "这是带声音的APN通知"
      }
    }
  }
  

  划重点：如果用自定义声音，必须把音频文件放进iOS App的主bundle或者Library/Sounds目录，还要在Info.plist里做好相关权限声明哦。

• 使用Firebase Admin SDK发送时
  以Node.js为例，代码参考如下：

  const admin = require('firebase-admin');
  admin.initializeApp();
  
  const message = {
    token: '你的设备推送令牌',
    apns: {
      payload: {
        aps: {
          sound: 'default'
        }
      }
    },
    notification: {
      title: '测试通知',
      body: '带声音的通知已送达'
    }
  };
  
  admin.messaging().send(message)
    .then(res => console.log('通知发送成功:', res))
    .catch(err => console.log('发送失败:', err));
  

你遇到的这个问题我之前也碰见过，核心是苹果的优先级规则和Firebase payload的映射逻辑没匹配上，咱们一步步理清楚：

首先，苹果明确要求：优先级设为10的通知，必须包含提醒（alert）、声音（sound）或角标（badge）中的至少一项，否则会直接拒绝请求。你之前按Firebase文档配置失败，大概率是只加了优先级配置，但没在aps里补上这些必填的触发字段；而直接在apns.headers里设apns-priority: "10"能成功，估计是当时的payload里已经通过notification字段包含了alert内容，FCM自动帮你映射到了aps.alert，刚好满足了苹果的要求。

正确的完整配置需要把优先级和触发字段结合起来，示例如下：

{
  "message": {
    "token": "你的iOS设备令牌",
    "apns": {
      "headers": {
        "apns-priority": "10" // 注意是字符串类型的"10"，不能用数字！
      },
      "payload": {
        "aps": {
          "alert": {
            "title": "高优先级通知",
            "body": "这是紧急通知，请查看"
          },
          "sound": "default" // 或者设"badge": 1，只要满足苹果的触发要求就行
        }
      }
    }
  }
}

另外还要避几个坑：

• apns-priority的值必须是字符串，不能写数字10，否则会触发FCM的参数校验失败；
• 如果你不想显式写aps.alert，也可以通过FCM的notification字段设置标题和内容，FCM会自动把这些内容同步到aps.alert里，同样能满足苹果的要求，示例：

  {
    "message": {
      "token": "你的设备令牌",
      "apns": {
        "headers": {
          "apns-priority": "10"
        }
      },
      "notification": {
        "title": "高优先级通知",
        "body": "通过FCM notification字段自动映射到aps"
      }
    }
  }
  

总结一下：优先级10的配置不能孤立存在，必须搭配至少一个触发字段（alert/sound/badge），这样才能同时通过Firebase和苹果的校验。

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