Firebase Messaging多播消息失败：'tokens'字段未被识别

AI 小北

2026-6-13

FCM多播发送提示“未识别字段'tokens'”的解决思路

核心原因：API端点使用错误

FCM v1 API中，单设备发送和多播发送对应的端点完全不同：

单设备发送用messages:send，请求体中使用token字段；
多播发送必须使用messages:sendMulticast端点，该端点才支持tokens字段（批量设备令牌列表）。

你当前的代码在多播场景下仍使用了单设备的messages:send端点，因此API会返回“未识别字段'tokens'”的错误。

具体修正步骤

替换请求URL
当设备令牌数量大于1时，将请求URL从messages:send改为messages:sendMulticast。
保持payload结构不变
多播场景下的messages:sendMulticast端点支持直接在message中使用tokens数组，无需调整现有payload的结构。

修正后的代码片段

project_id = service_account['project_id'] 
headers = {
    'Authorization': f'Bearer {access_token}',
    'Content-Type': 'application/json; UTF-8',
    "access_token_auth": True,
}
# Construct message payload for multicast
if len(device_tokens) > 1:
    # 修正：使用多播专用端点
    url = f'/v1/projects/{project_id}/messages:sendMulticast'
    payload = {
        'message': {
            'tokens': device_tokens
        }
    }
else:
    # 单设备发送保持原端点
    url = f'/v1/projects/{project_id}/messages:send'
    payload = {
        'message': {
            'token': device_tokens[0]
        }
    }
if notification:
    payload['message']['notification'] = notification
# Make request
conn = http.client.HTTPSConnection('fcm.googleapis.com')
conn.request('POST', url, dumps(payload), headers)
response = conn.getresponse()
status = response.status
reason = response.reason
response_str = loads(response.read().decode('utf-8'))
conn.close()