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

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

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

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

Expo 推送通知服务常见问题解答

¥Expo push notification service FAQ

推送通知服务的费用

¥Cost of the push notification service

通过 Expo 推送通知服务发送通知没有任何成本。

¥There is no cost associated with sending notifications through Expo 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 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 存储推送通知内容的时间不会超过将其传送到 Google 和 Apple 运营的推送通知服务所需的时间。通知仅存储在内存和消息队列中，而不存储在数据库中。

¥Expo doesn't store the contents of push notifications any longer than it takes to deliver them to the push notification services operated by Google and Apple. Notifications are stored only in memory and in message queues, not 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 and Apple follow their policies to deliver the notification to the device.

ExpoPushToken 何时以及为何改变

¥When and why does the ExpoPushToken change

ExpoPushToken 在应用升级过程中保持不变。在 Android 上，重新安装应用可能会导致令牌发生变化。在 iOS 上，即使卸载应用并重新安装后，令牌也保持不变。

¥The ExpoPushToken remains the same across app upgrades. On Android, reinstalling the app may result in the token changing. On iOS, the token also remains the same even after uninstalling the app and reinstalling it.

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

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

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

¥The ExpoPushToken never expires. 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 token.

推送通知故障排除

¥Push notifications troubleshooting

通知不起作用

¥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 ensures 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"
  ]
}'

通知在开发模式下有效，但在发布模式下无效

¥Notifications work in development, but not in release mode

这表明你的凭据配置错误或者根本没有在生产应用中配置它们。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 results 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 上显示通知的可能性最大。

¥Setting the priority to high gives your notification the greatest likelihood that 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 push notification service and instead, would like to communicate with Google and Apple directly, see Send notifications with FCM and APNs.

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.