本页面提供了问题排查帮助,并解答了有关 Cloud Messaging 的常见问题。
Firebase Cloud Messaging 问题排查及常见问题解答
如未另行说明,那么本页面中的内容已根据知识共享署名 4.0 许可获得了许可,并且代码示例已根据 Apache 2.0 许可获得了许可。有关详情,请参阅 Google 开发者网站政策。Java 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC):2025-08-21。
[null,null,["最后更新时间 (UTC):2025-08-21。"],[],[],null,["\u003cbr /\u003e\n\nThis page provides troubleshooting help and answers to frequently asked\nquestions about Cloud Messaging.\n\n\u003cbr /\u003e\n\nWhat's the\ndifference between the the Notifications composer and FCM?\n\n\u003cbr /\u003e\n\nFirebase Cloud Messaging provides a complete set of messaging\ncapabilities through its client SDKs and HTTP server\nprotocol. For deployments with more complex messaging requirements,\nFCM is the right choice.\n\nThe Notifications composer is a lightweight, serverless messaging\nsolution built on Firebase Cloud Messaging. With a user-friendly\ngraphical console and reduced coding requirements,\nthe Notifications composer lets users send messages to\nre-engage and retain users, foster app growth, and support marketing\ncampaigns.\n\n\u003cbr /\u003e\n\n| **Capabilities** | | **Notifications composer** | **Cloud Messaging** |\n|------------------|------------------------------------------------------------------|----------------------------|---------------------|\n| **Target** | Single device | | |\n| | Clients subscribed to topics (i. e. weather) | | |\n| | Clients in predefined user segment (app, version, language) | | |\n| | Clients in specified analytics audiences | | |\n| | Clients in device groups | | |\n| | Upstream from client to server | | |\n| **Message Type** | Notifications up to 2kb | | |\n| | Data messages up to 4kb | | |\n| **Delivery** | Immediate | | |\n| | Future client device local time | | |\n| **Analytics** | Built-in Notifications analytics collection and funnel analytics | | |\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\nDo I need to use other\nFirebase services in order to use FCM?\n\n\u003cbr /\u003e\n\nYou can use Firebase Cloud Messaging as a standalone component, without using\nother Firebase services.\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\nWhy do my targeted devices\napparently fail to receive messages?\n\n\u003cbr /\u003e\n\nWhen it looks like devices haven't successfully received messages, check first\nfor these two potential causes:\n\n**Foreground message handling for notification messages.** Client apps need to\nadd message handling logic to handle notification messages when the app is in\nthe foreground on the device. See the details for\n[iOS](/docs/cloud-messaging/downstream#receive_downstream_messages) and\n[Android](/docs/cloud-messaging/downstream#sample-receive).\n\n**Network firewall restrictions.** If your organization has a firewall that\nrestricts the traffic to or from the Internet, you need to configure it to allow\nconnectivity with FCM in order for your Firebase Cloud Messaging client\napps to receive messages. The ports to open are:\n\n- 5228\n- 5229\n- 5230\n\nFCM usually uses 5228, but it sometimes uses 5229 and 5230.\nFCM doesn't provide specific IPs, so you should allow your firewall to\naccept outgoing connections to all IP addresses contained in the IP blocks\nlisted in Google's [ASN of 15169](https://bgp.he.net/AS15169#_prefixes).\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\nWhy\nisn't `onMessageReceived` being called in my Android app?\n\n\u003cbr /\u003e\n\nWhen your app is in the background, [notification\nmessages](/docs/cloud-messaging/concept-options#notifications_and_data_messages)\nare displayed in the system tray, and `onMessageReceived` is not called. For\nnotification messages with a data payload, the notification message is displayed\nin the system tray, and the data that was included with the notification message\ncan be retrieved from the intent launched when the user taps on the\nnotification.\n\nFor more information, see [Receive and handle messages](/docs/cloud-messaging/downstream#sample-receive).\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\nWhy do I get 404\nerror when I send messages to an active app instance restored from a backup?\n\n\u003cbr /\u003e\n\nFID (Firebase Installation ID) is the identifier of an app instance. By default,\nFirebase Installation data is backed up and restored. So in the restoration\ncase, the restored app instance and the original app instance share the same\nFID. Since FCM only stores one token per FID, if both the original app instance\nand the restored app instance are in use, then when one app instance registers\nwith FCM, the other app instance's token is removed, which causes 404\nerrors.\n\nWe recommend developers to do the following in their app:\n\n- [Exclude](https://developer.android.com/identity/data/autobackup#xml-include-exclude) Firebase installation data in backup. The Firebase installation data is stored in a `PersistedInstallation....json` file. The filename is a constant for an app. For example, `\u003cexclude domain=\"file\" path=\"PersistedInstallation.W0R...GQ.json\"\n /\u003e`\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\nApple\nannounced they're deprecating the legacy binary protocol for APNs. Do I need to\ndo anything?\n\n\u003cbr /\u003e\n\nNo. Firebase Cloud Messaging switched to the HTTP/2-based APNs protocol in 2017.\nIf you're using FCM to send notifications to iOS devices, there should\nbe no action required on your part.\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\nFCM quotas and limits\n\n\u003cbr /\u003e\n\nHow do I notify a large customer\nbase within 2 minutes?\n\n\u003cbr /\u003e\n\nThis use case cannot be supported. You must spread your traffic out over 5\nminutes.\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\nMy app notifies users of\nevents, and these messages must be delivered immediately to support my business\nmodel. Can I get more quota?\n\n\u003cbr /\u003e\n\nUnfortunately, we cannot grant quota increases for this reason. You must spread\nyour traffic out over 5 minutes to [avoid spiky\ntraffic](/docs/cloud-messaging/scale-fcm#avoid-spikes).\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\nMy messages are about\nscheduled events. How can I send all traffic at the top of the hour?\n\n\u003cbr /\u003e\n\nWe recommend that you start sending the notifications at least 5 minutes prior\nto the event. Alternatively, send [data\nmessages](/docs/cloud-messaging/concept-options#data_messages) and implement\nyour platform's analog of `onMessageReceived` handler to schedule local\nnotifications ahead of time.\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\nHow can I monitor my quota usage?\n\n\u003cbr /\u003e\n\nSee Google Cloud guidance on how to [chart and monitor quota metrics](https://cloud.google.com/monitoring/alerts/using-quota-metrics).\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n429 errors are hard\nfor me and my business to handle. Can I get an exemption or more quota to avoid\ngetting 429s?\n\n\u003cbr /\u003e\n\nWhile we understand that quota limits can be challenging, quotas are vital to\nkeeping the service reliable and we can't grant exemptions. Use retries to\nproperly [handle 429 errors](/docs/cloud-messaging/scale-fcm#handling-retries).\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\nHow long will it\ntake for my quota increase request to be fulfilled?\n\n\u003cbr /\u003e\n\nYour [quota increase\nrequest](/docs/functions/quotas#when_you_reach_a_quota_limit) depends on your\nuse of FCM. In any case, you can expect an answer in a few business\ndays. In some cases, there may be some back-and-forth regarding your usage of\nFCM and various circumstances, which can prolong the process. If all\nrequirements are met, most requests will be handled within 2 weeks.\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\nCan I get more quota for a\ntemporary event?\n\n\u003cbr /\u003e\n\nYou can request additional quota to support an event lasting up to 1 month.\nFile the request at least 1 month in advance of the event and with clear details\non when the event starts and ends, and FCM will make every practical\neffort to fulfill the request. If granted, these quota increases will be\nreverted after the event's end date.\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\nIs my current quota subject\nto change?\n\n\u003cbr /\u003e\n\nWhile Google won't do so lightly, quotas may be changed as needed to protect the\nintegrity of the system. When possible, Google will notify you in advance of\nsuch changes. Keep your [Cloud MSA\ncontacts](https://cloud.google.com/docs/cloud-msa) updated to increase the\nchances of receiving service announcements.\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e"]]