跳转到主要内容
如果您的网站出现问题，请参阅网页推送故障排除指南。

​
故障排除步骤

​
查看设置说明并更新 SDK

我们经常发布更新，包含错误修复、改进和对最新操作系统更改的支持。确保您使用的是最新 SDK 版本并已遵循设置说明。

移动 SDK 设置

旨在帮助预防常见问题并测试集成的设置说明。

​
查看常见故障排除指南

通知未显示或延迟

推送通知未出现在设备上或有延迟。

通知图像未显示

图像未出现在通知的展开视图中。

通知点击率

通知的点击率低或无点击。

重复通知

通知在设备上多次显示。

应用内消息故障排除

应用内消息未按预期显示或运行。

​
检查您的应用是否存在常见问题

​
阻止推送显示的 OneSignal 方法

检查您的应用是否有 optOut() 之类的方法，例如 OneSignal.User.pushSubscription.optOut()，或者您是否通过 REST API 设置了 enabled: false。这会将推送订阅状态设置为 unsubscribed。详情请参阅 Mobile SDK 参考。 如果在发送推送时应用处于打开状态，您可能通过 preventDefault() 方法阻止了推送显示。这通常在前台事件监听器或 Android 通知服务扩展中设置。

​
Firebase Messaging 或其他 SDK 冲突

如果您的应用还包含 Firebase Messaging SDK 或其他推送通知 SDK，请验证它不会在 OneSignal 处理消息之前拦截消息。 此问题通常发生在以下情况：
  • 通知在 OneSignal 中显示为已送达，但从未出现在设备上。
  • 应用同时包含 OneSignal 和 firebase_messaging（或自定义 FirebaseMessagingService）。
  • 移除 Firebase Messaging 后推送正常，但两个 SDK 同时存在时失败。
  1. 检查您的 AndroidManifest.xml 中是否有旧版 Firebase 接收器，例如 com.google.firebase.iid.FirebaseInstanceIdReceiver，如果 OneSignal 负责推送传递，请将其删除/有条件地排除。
  2. 检查是否有覆盖 onMessageReceived 的自定义 FirebaseMessagingService 实现（或 Flutter 中的 firebase_messaging 等库）。如果另一个服务完全处理或抑制了消息，它可能会在 OneSignal 显示通知之前消费 FCM 有效载荷。
  3. 避免调用 Firebase 令牌管理 API，例如：FirebaseMessaging.getToken() 或 FirebaseMessaging.deleteToken()。
如果 OneSignal 负责推送传递，它应该是唯一管理推送令牌生命周期的 SDK。直接获取或管理 FCM 令牌可能导致令牌所有权冲突和不一致的传递行为。 如果您需要为其他系统获取设备推送令牌，请从 OneSignal 读取（例如 User.pushSubscription.token），并使用 SDK 的观察者 API 监听订阅/令牌变化。

​
测试您 SDK 的示例项目

检查您的问题是否可以使用我们工程团队为每个 SDK 维护的示例项目重现。

​
检查错误日志

在进一步诊断之前收集日志数据：
  • 遵循捕获调试日志指南。
  • 查找可能解释该行为的错误、警告或弃用通知。

捕获调试日志

如何启用详细日志记录并捕获 SDK 输出以进行故障排除。

​
联系支持

如果您仍遇到问题，请联系 support@onesignal.com 并提供：
  • 您的 OneSignal 应用 ID
  • 受影响设备的外部 ID 和/或订阅 ID
  • 通知 ID 或仪表板中通知的链接（如适用）
  • 重现问题的设备调试日志

​
常见错误

​
APNS 委托从未触发

“APNS Delegate Never Fired”和”APNS 3000”等错误是 Apple 的超时消息，表示设备无法连接到 Apple 的 APNS 服务器。最常见于以下情况：
  • 在 APNS 开发环境中测试
  • 将多个推送通知依赖项或原生 iOS 推送 API 与 OneSignal 一起使用
  • 临时连接问题——通常在用户下次开始新会话时自动解决（应用在后台运行 30 秒以上，然后重新打开）
解决步骤：
  1. 删除所有其他推送通知依赖项或原生 iOS 推送 API，仅使用 OneSignal。错误解决后，可以重新添加其他代码。联系 support@onesignal.com 获取共存最佳实践。
  2. 检查设备调试日志了解更多详情。
  3. 如果错误持续存在，请联系支持。
如果您使用 Capacitor，请添加此配置以让 OneSignal 处理推送通知。 
{
  "ios": {
    "handleApplicationNotifications": false
  }
}

​
强制关闭后点击通知时应用无法打开

确保您不是在 Debug 构建上进行测试。例如，对于 Flutter 应用，您可以：
  • 通过 Flutter 使用发布构建，例如 flutter run --release（需要物理设备）
  • 将 Xcode scheme 更新为 Release 而不是 Debug

​
相关页面

移动 SDK 设置

所有受支持的移动和跨平台 SDK 的设置说明。

捕获调试日志

如何捕获 SDK 日志以进行故障排除。

网页推送故障排除

排除网页推送通知问题。

移动 SDK 参考

OneSignal 移动 SDK 的完整 API 参考。

​
常见问题

​
如果我在应用中更改 OneSignal 应用 ID 会发生什么？

在您应用的初始化代码中更改 OneSignal 应用 ID 将在用户更新并打开应用到最新版本时在新应用 ID 下创建全新的用户和推送订阅。 如果您的 iOS bundle ID 和/或 Android package ID 相同，那么设备将继续保持相同的推送订阅状态。用户数据将是全新的，即您需要在新记录上重新添加您的别名、标签、电子邮件地址、电话号码。 如果 iOS bundle ID 或 Android package ID 不同，那么这是一个全新的应用，应该有不同的推送证书/密钥。

​
OneSignal 可以在本地部署的封闭网络中发送推送通知吗？

只要您封闭网络上的计算机可以访问您要支持的推送网关服务器，这就可以工作： 如果网络完全与互联网断开连接，则无法通过标准操作系统/浏览器服务传递推送通知，这是我们支持的。