技术 FAQ
本文按“先准备信息、再定位链路、最后处理具体问题”的顺序整理极光推送技术问题。遇到“推送成功但收不到”时，建议先完成基础排查，再进入具体场景。
如果您正在判断业务场景应该选哪种能力，请查看 产品与场景 FAQ；如果已经出现错误码、收不到推送、厂商通道不生效、点击不跳转等问题，建议从本文开始排查。
快速定位
| 如果您遇到 | 建议查看 |
|---|---|
| 不知道排查需要哪些参数 | 排查前需要准备哪些信息 |
| API 成功但用户没收到 | 接口成功但用户没收到 |
| 打开 App 能收到，杀死 App 后收不到 | App 被杀后收不到 |
| 没有走 Android 厂商通道 | 厂商通道排查 |
| 通知送达但通知栏不展示 | 送达但不展示 |
| 厂商通道点击不跳转 | 点击跳转排查 |
| 标签、别名不命中 | 标签别名排查 |
| iOS 环境不匹配 | iOS 环境排查 |
排查准备
排查前需要准备哪些信息？
建议先准备以下信息，能显著减少来回确认成本：
- AppKey。
- Message ID，也就是 API 返回或控制台推送记录中的
msg_id。 - 目标设备当前有效的 Registration ID。
- 推送时间、平台、机型、系统版本、App 版本、SDK 版本。
- 推送请求体或控制台推送配置截图。
- 排查工具中的消息生命周期结果。
- 客户端日志和厂商 token 获取情况。
相关文档：
如何获取 AppKey、Registration ID 和 Message ID？
- AppKey 可在极光控制台应用信息中查看。
- Registration ID 由客户端初始化 JPush 成功后获取，用于标识当前 App 在当前设备上的推送身份。
- Message ID 可从 API 返回的
msg_id获取，也可在控制台推送记录中查看。
详细说明参考 排查必要参数获取办法。
如何获取客户端日志？
如果集成或收消息存在异常，建议先获取客户端日志进行初步排查。若根据日志仍无法定位问题，可将日志连同 AppKey、Message ID、Registration ID 一并提供给技术支持。
日志获取方式参考 客户端日志获取方法。
送达与通道
推送接口返回成功，但用户没收到，先查什么？
Push API 返回成功表示极光服务已接收并处理推送请求，不代表每台设备都已收到或展示通知。
推荐排查顺序：
- 保存 API 返回的
msg_id。 - 获取目标设备当前有效的 Registration ID。
- 在排查工具中使用 Message ID + Registration ID 查询消息生命周期。
- 使用设备查询确认设备是否属于当前 AppKey、是否在线、通知权限是否开启、厂商 token 是否正常。
- 查看推送记录和折损原因，判断问题发生在请求、目标、通道、送达还是展示阶段。
相关文档：
打开 App 能收到，杀死 App 后收不到，是什么原因？
如果只集成了极光自建通道，设备需要依赖 App 长连接在线才能及时收到消息。App 被系统杀死或长连接不在线时，消息会缓存到极光服务器，等待 App 下次在线后再下发。
如果希望离线时也尽量收到通知：
- Android 需要集成对应厂商通道。
- 服务端检查
third_party_channel下发策略是否符合预期。 - 对自定义消息离线提醒场景，可使用自定义消息转厂商通知。
- 对强到达业务，可配置短信补充。
相关文档：
为什么消息没有走厂商通道下发？
常见原因包括厂商 SDK 未集成成功、厂商 token 未获取、厂商参数配置错误、下发策略不匹配、非 VIP 厂商通道资源受限或厂商配额不足。
建议检查：
- 客户端是否成功集成对应厂商 SDK。
- 设备查询中是否能看到对应厂商 token。
- 控制台厂商通道配置是否正确。
- API 中
options.third_party_channel的distribution是否符合预期。 - 当前厂商配额、QPS 和消息分类是否受限。
- 非 VIP 应用是否触发厂商通道下发量限制。
相关文档：
推送已经送达设备，但通知栏没有展示，怎么排查？
送达不等于展示。通知栏不展示通常与通知权限、系统通知渠道、前台展示逻辑、厂商限制、内容规范或设备系统策略有关。
建议检查：
- 设备通知权限是否关闭。
- Android 8.0 及以上是否配置了正确的 NotificationChannel。
- 通知内容是否符合厂商规范，避免纯数字、
test、测试等无意义内容。 - App 前台时是否由客户端自己处理展示逻辑。
- 厂商通道是否返回内容、分类或权限相关失败。
相关文档：
自定义消息收不到，和通知收不到是同一个问题吗？
不完全一样。通知可以通过通知栏展示；自定义消息默认不会展示到通知栏，通常依赖 App 在线后由客户端回调处理。
建议检查：
- 客户端是否实现自定义消息回调。
- App 是否在线，长连接是否正常。
- 是否期望离线也提醒用户；如果是，应使用自定义消息转厂商通知。
- 是否只在部分厂商支持自定义消息厂商通道下发。
- 服务端是否同时误传了
notification和notification_3rd。
相关文档：
目标与参数
推送返回 1011，提示找不到目标用户，怎么处理？
1011 通常表示没有满足条件的推送目标，例如目标 Registration ID 不属于当前 AppKey、别名或标签未绑定成功、目标用户长期不活跃，或推送条件与实际绑定值不一致。
建议检查：
- Registration ID 是否属于当前 AppKey。
- 目标设备是否卸载重装、清除数据或重新注册。
- alias、tag、segment 是否与客户端实际上报一致。
- 推送目标是否为空或条件过窄。
- 目标用户是否已长期不活跃。
相关文档：
标签、别名推送不命中，怎么排查？
标签和别名常见问题包括绑定失败、绑定未生效、绑定数量超限、目标值和推送值不一致、设备重新注册后未重新绑定等。
建议检查：
- 客户端设置 tag、alias 的回调结果是否成功。
- 同一用户多设备绑定关系是否符合业务预期。
- 推送时 tag、alias 的大小写、特殊字符和长度是否正确。
- Registration ID 变化后是否重新同步用户标识。
- 使用推送记录确认目标条件是否与发送时保持一致。
相关文档：
点击与展示
厂商通道点击通知无法跳转，怎么排查？
厂商通道点击跳转通常需要客户端和服务端同时配置正确。
建议检查：
- 客户端是否配置目标 Activity、action、scheme 或 deeplink。
- 服务端是否按 Android 通知点击跳转 文档传递
intent。 - OPPO 和 FCM 等通道是否按要求传递 action 或 Activity 全名。
- 跳转参数包含
#、;等特殊字符时，是否使用third_url_encode做兼容。 - 落地页是否支持通过通知 extras 恢复业务上下文。
third_url_encode 示例：
{
"extras": {
"third_url_encode": true
}
}
如何设置自定义铃声？
目前仅极光通道和部分厂商通道支持自定义铃声。不同厂商对铃声文件路径、首次创建通知渠道、系统版本等有差异限制，详情参考 自定义铃声设置。
如何设置通知栏图片？
极光推送支持大图片、右侧图标、状态栏小图标等能力。不同厂商和系统版本支持范围不同，详情参考 图标设置。
iOS 相关
iOS 推送环境不匹配（errcode：-16）怎么处理？
排查工具查询消息生命周期显示 -16 iOS 推送环境不匹配 时，通常表示设备注册 token 的环境与推送请求选择的 APNs 环境不一致。
建议检查：
- App 当前安装包是开发环境还是生产环境。
- 证书或 Token Authentication 配置是否与 Bundle ID 匹配。
- API 请求中的
options.apns_production是否设置正确。 - 测试设备是否重新安装过 App，并重新获取过 token。
相关文档：
