推送通知故障排除和常见问题解答

有关 Expo 推送通知服务的常见问题集合。

使用 expo-notifications 库和 Expo 的推送通知服务设置推送通知时的常见问题和常见问题解答的集合。

¥A collection of common issues and FAQs when setting up push notifications with the expo-notifications library and Expo's push notification service.

Expo 推送通知服务

¥Expo's push notification service

推送通知服务的费用

¥Cost of the push notification service

通过 Expo 的经典推送通知服务发送通知不需要任何费用。

¥There is no cost associated with sending notifications through Expo's classic push notification service.

发送通知的限制

¥Limit of sending notifications

每个项目每秒可发送的通知数上限为 600 个。如果超过此速率，后续请求将失败，直到速率再次低于每秒 600 个。

¥There is a limit of 600 notifications per second per project that can be sent. If you exceed this rate, subsequent requests will fail until the rate falls below 600 per second again.

为了获得最佳结果，我们建议你向服务器添加限制（在 expo-server-sdk-node 中自动处理）和重试逻辑。

¥For best results, we recommend you add throttling (which is handled automatically in the expo-server-sdk-node) and retry logic to your server.

不强制使用 Expo 的推送通知服务

¥Using Expo's push notification service is not mandatory

你可以使用 Expo 项目的任何推送通知服务。expo-notifications 的 getDevicePushTokenAsync 方法 允许你获取原生设备推送令牌，然后你可以将其与其他服务甚至 直接通过 FCM 和 APN 发送通知 一起使用。

¥You can use any push notification service for Expo projects. The getDevicePushTokenAsync method from expo-notifications allows you to get the native device push token, which you can then use with other services, or even send your notifications directly through FCM and APNs.

与通知服务的连接已加密

¥Connections to notification service are encrypted

Expo 与 Apple 和 Google 的连接已加密并使用 HTTPS。

¥Expo's connections to Apple and Google are encrypted and use HTTPS.

通知的内容不被存储

¥Contents of the notification are not stored

Expo 存储推送通知内容的时间不会超过将通知发送到 Apple、Google 等运营的推送通知服务所需的时间。通知仅存储在内存和消息队列中，不存储在数据库中。

¥Expo doesn't store the contents of push notifications any longer than it takes to deliver the notifications to the push notification services operated by Apple, Google, and so on. Notifications are stored only in memory and in message queues and not stored in databases.

Expo 工作线程可以看到通知内容

¥Contents of the notifications may be seen by Expo staff

如果 Expo 团队正在积极调试推送通知服务，我们可能会看到通知内容（例如，在断点处），但 Expo 否则无法看到推送通知内容。

¥If the Expo team is actively debugging the push notifications service, we may see notification contents (for example, at a breakpoint) but Expo cannot see push notification contents otherwise.

交货保证

¥Delivery guarantees

Expo 尽最大努力向 Google 和 Apple 运营的推送通知服务发送通知。Expo 的基础设施旨在至少向底层推送通知服务传递一次。在某些情况下，通知可能会多次发送给 Google 或 Apple，或者根本不会发送，尽管这种情况很少见。

¥Expo makes the best effort to deliver notifications to the push notification services operated by Google and Apple. Expo's infrastructure is designed for at-least-once delivery to the underlying push notification services. In some cases, a notification may be delivered to Google or Apple more than once or not at all, although these cases are rare.

将通知移交给底层推送通知服务后，Expo 会创建一个 "推送收据" 来记录移交是否成功。推送收据表示底层推送通知服务是否收到通知。

¥After a notification has been handed off to an underlying push notification service, Expo creates a "push receipt" that records whether the handoff was successful. A push receipt denotes whether the underlying push notification service received the notification.

最后，Google、Apple 等的推送通知服务遵循其策略将通知传递到设备。

¥Finally, the push notification services from Google, Apple, and so on follow their policies to deliver the notification to the device.

推送通知

¥Push notifications

通知不起作用

¥Notifications aren't working

推送通知有很多移动部分，因此这可能是由于多种原因造成的。要缩小范围，请检查 推票 和 推送收据 是否有错误消息。

¥Push notifications have a lot of moving parts, so this can be due to a wide variety of reasons. To narrow things down, check the push ticket and push receipt for error messages.

你还可以通过在应用中测试 本地通知 来进一步缩小范围。这将确保所有客户端逻辑都是正确的，并将范围缩小到服务器端或应用凭据。

¥You can also narrow things even further by testing local notifications in your app. This will ensure all of your client-side logic is correct, and narrow things down to the server side or app credentials.

curl -H "Content-Type: application/json" -X POST "https://exp.host/--/api/v2/push/send" -d '{
  "to": "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]",
  "title":"hello",
  "body": "world"
}'

curl -H "Content-Type: application/json" -X POST "https://exp.host/--/api/v2/push/getReceipts" -d '{
  "ids": [
    "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
  ]
}'

ExpoPushToken 何时以及为何改变

¥When and why does the ExpoPushToken change

ExpoPushToken 在应用升级中将保持不变。在 iOS 上，即使卸载应用并重新安装后，它也将保持不变。在 Android 上，这会导致推送令牌发生变化。

¥The ExpoPushToken will remain the same across app upgrades. On iOS, it will also remain the same even after uninstalling the app and reinstalling it. On Android, this results in the push token changing.

如果你更改 applicationId 或 experienceId（通常是 @expoUsername/projectSlug），它也会更改。

¥It will also change if you change your applicationId or experienceId (usually @expoUsername/projectSlug).

ExpoPushToken 永远不会过期。但是，如果你的一位用户卸载了该应用，你将从 Expo 的服务器返回 DeviceNotRegistered 错误。这意味着你应该停止向此应用发送通知。

¥The ExpoPushToken will never expire. However, if one of your users uninstalls the app, you'll receive a DeviceNotRegistered error back from Expo's servers. This means you should stop sending notifications to this app.

通知在开发中起作用，但在构建应用后不起作用

¥Notifications work in development, but not after building the app

这表明你的凭据配置错误或者根本没有在生产应用中配置它们。Expo Go 使用 Expo 的凭证，允许在开发中处理通知。

¥This indicates that you have either misconfigured your credentials or didn't configure them at all in your production app. Expo Go uses Expo's credentials, which allows working on notifications in development.

当你为应用商店构建应用时，你需要生成并使用自己的凭据。在 Android 上，请遵循 本指南。在 iOS 上，这由你的 按键 处理（撤销与你的应用关联的推送键将导致你的通知无法发送。要解决此问题，请使用 eas credentials 添加新的推送键）。

¥When you build your app for the app stores, you need to generate and use your own credentials. On Android, follow this guide. On iOS, this is handled by your push key (revoking the push key associated with your app will result in your notifications failing to be delivered. To fix that, add a new push key with eas credentials).

欲了解更多信息，请参阅 应用签名。

¥For more information, see app signing.

Android 上的通知有时会停止发送

¥Notifications occasionally stop coming through on Android

这可能是由于你发送的通知的 priority 级别所致。你可以了解更多有关 安卓优先 的信息。Expo 接受四个优先事项：

¥This is likely due to the priority level of the notifications you're sending. You can learn more about Android priority. Expo accepts four priorities:

• default：手动映射到 Apple 和 Google 记录的默认优先级

  ¥default: manually mapped to the default priority documented by Apple and Google

• high：映射到 Apple 和 Google 记录的高优先级

  ¥high: mapped to the high priority level documented by Apple and Google

• normal：映射到 Apple 和 Google 记录的正常优先级

  ¥normal: mapped to the normal priority level documented by Apple and Google

• （优先级省略）：完全按照指定 default 的方式处理

  ¥(priority omitted): treated exactly as if default were specified

将优先级设置为 high 可以让 Android 最有可能显示该通知。

¥And setting the priority to high gives your notification the greatest likelihood that the Android will display the notification.

处理过期的推送通知凭据

¥Handle expired push notification credentials

当你的推送通知凭据过期时，运行 eas credentials，选择 iOS 和构建配置文件，然后删除推送通知密钥并生成一个新密钥。

¥When your push notification credentials have expired, run eas credentials, choose iOS and a build profile, then remove your push notification key and generate a new one.

发送通知时出现错误消息

¥Error message when sending a notification

检查返回的推送票证或收据的 details 属性以获取更多信息。读这个 用于常见错误代码响应及其相关解决方案。

¥Check the details property of the returned push ticket or receipt for more information. Read this for common error code responses and their associated solutions.

在 iOS 上获取推送令牌需要很长时间

¥Fetching a push token takes a long time on iOS

在 iOS 上，getDevicePushTokenAsync 和 getExpoPushTokenAsync 有时可能需要很长时间才能解析。正如 Apple 的 推送通知故障排除 技术说明中所述，这超出了 expo-notifications 的控制范围：

¥getDevicePushTokenAsync and getExpoPushTokenAsync can sometimes take a long time to resolve on iOS. This is outside of expo-notifications's control, as stated in Apple's Troubleshooting Push Notifications technical note:

这不一定是错误情况。该系统可能根本没有互联网连接，因为它超出了任何手机信号塔或 Wi-Fi 接入点的范围，或者它可能处于飞行模式。你的应用不应将其视为错误，而应正常继续，仅禁用依赖推送通知的功能。

¥This is not necessarily an error condition. The system may not have Internet connectivity at all because it is out of range of any cell towers or Wi-Fi access points, or it may be in airplane mode. Instead of treating this as an error, your app should continue normally, disabling only that functionality that relies on push notifications.

以下是我们的社区成员解决此问题的一些方法：

¥Here are some ways our community members have resolved this issue:

各种各样的

¥Miscellaneous

直接通过 FCM 和 APN 发送通知

¥Sending notifications directly through FCM and APNs

如果你不使用 Expo 推送通知服务，而是想直接与 Google 和 Apple 通信，请参阅 使用 FCM 和 APN 发送通知，特别注意有效负载格式，因为提供不同的格式可能会导致两个平台上出现意外行为。

¥If you are not using Expo's push notification service and instead, would like to communicate with Google and Apple directly, see Send notifications with FCM and APNs, paying special attention to the payload formats, since providing different formats can result in unexpected behavior on both platforms.

Android 上的通知图标是灰色或白色方块

¥Notification icon on Android is a grey or white square

这表明你提供的图片资源存在问题。图片应为全白色并具有透明背景（这是 Google 而非 Expo 所要求和强制执行的）。欲了解更多信息，请参阅 本文。

¥This indicates an issue with the image asset you're providing. The image should be all white with a transparent background (this is required and enforced by Google, not Expo). For more information, see this article.

发送通知时播放自定义声音

¥Play a custom sound when I send a notification

Expo 推送通知服务目前不支持自定义声音。你将需要在独立应用中直接将 FCM 和 APN 与从 expo-notifications 收到的原生设备令牌结合使用。

¥The Expo push notification service currently doesn't support custom sounds. You will need to use FCM and APNs directly with the native device tokens received from expo-notifications in standalone apps.

从 Expo 的 LegacyNotifications 库迁移

¥Migrate from Expo's LegacyNotifications library

有关如何从 Expo 的 LegacyNotifications 库迁移到使用 expo-notifications 的更多信息，请参阅 迁移指南。

¥For more information on how to migrate from Expo's LegacyNotifications library to use expo-notifications, see the migration guide.