原生移动开发 / 系统课时

定位推送消息为什么收不到

定位推送消息为什么收不到

推送收不到时,最有效的方法不是反复点“发送测试”,而是沿着消息链路逐段确认:服务端有没有成功提交、目标 Token 是否有效、FCM 或厂商通道有没有接受消息、设备是否在线,以及消息到达后是否被当前 App 状态下的处理逻辑接住。每一段都有不同的证据。

学习目标

  • 能把“发送失败”和“发送成功但设备没看到”区分开。
  • 能核对 Token、FCM 返回结果和设备联网状态。
  • 能根据前台、后台状态判断消息究竟进入回调还是系统通知栏。

先从服务端发送结果查起

第一步确认服务端请求是否真的提交成功。FCM HTTP v1 对无效 Token、参数错误、发送配额和服务不可用分别返回不同错误;例如 UNREGISTERED 表示注册已失效,UNAVAILABLE 表示服务端暂时不可用,后者应结合 Retry-After 和指数退避处理。([Firebase][2])

排查单设备推送时,建议先保存一次完整的服务端响应,再进入客户端检查。下面是一个使用 curl 调用 FCM HTTP v1 的最小示例。示例中的 <PROJECT_ID>、<ACCESS_TOKEN> 和 <FCM_TOKEN> 都是占位符,实际值可能不同。

bash
curl -sS -X POST "https://fcm.googleapis.com/v1/projects/<PROJECT_ID>/messages:send" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json; charset=UTF-8" \
  -d '{
    "message": {
      "token": "<FCM_TOKEN>",
      "notification": {
        "title": "测试消息",
        "body": "推送链路验证"
      }
    }
  }'

预期结果

text
成功时:HTTP 200,并返回包含 message 标识的响应。
失败时:返回 4xx/5xx,并在响应中给出状态或 FCM 错误码,例如 UNREGISTERED、INVALID_ARGUMENT 或 UNAVAILABLE。

这里的关键判断是:服务端拿到成功响应,只能证明 FCM 后端接受了发送请求,不等于用户已经在界面看到通知。 FCM 的设备侧链路还会经过平台传输层,并受设备在线状态和 App 当前状态影响。([Firebase][3])

核对 Token 是否还是当前设备的

第二步检查数据库保存的 Token 是否与当前安装实例对应。FCM Token 可能在应用恢复到新设备、卸载重装或清除应用数据等情况下发生变化,因此客户端应获取最新 Token 并同步到服务端,服务端也应在收到失效注册结果后停止继续向该 Token 发送。([Firebase][4])

客户端可以用下面的 Kotlin 片段确认当前安装实例拿到的 Token。该片段需要在已经接入 Firebase Messaging 的 Android 应用上下文中运行。

kotlin
import android.util.Log
import com.google.firebase.messaging.FirebaseMessaging

fun logCurrentFcmToken() {
    FirebaseMessaging.getInstance().token
        .addOnCompleteListener { task ->
            if (!task.isSuccessful) {
                Log.w("PushDiag", "获取 FCM Token 失败", task.exception)
                return@addOnCompleteListener
            }

            val token = task.result
            Log.d("PushDiag", "当前 FCM Token=${token.take(12)}...")
        }
}

预期结果

text
成功:Logcat 出现当前安装实例对应的 FCM Token 前缀。
失败:Logcat 出现“获取 FCM Token 失败”及异常信息。

不要把完整 Token 长期写入普通业务日志;诊断时记录短前缀或哈希更适合。服务端收到 UNREGISTERED 时,应删除或停用对应注册记录,而不是无限重试。([Firebase][2])

判断消息到了哪里

第三步检查 Android App 当前处于前台还是后台。对于 Android FCM,通知消息在前台通常进入 onMessageReceived();当应用处于后台时,通知消息通常由系统通知栏展示,onMessageReceived() 不会按同样方式被调用。通知加 data 的消息在后台时,通知进入系统通知栏,而 data 可在用户点击后由启动 Activity 的 Intent extras 获取。([Firebase][5])

这意味着“onMessageReceived() 没日志”并不能单独证明推送没到。例如 App 在后台,而服务端发送的是 notification 消息时,首先应该去看系统通知栏与点击后的 Intent 数据,而不是只盯着 FirebaseMessagingService 日志。

若消息到达回调后还要下载图片、查询接口或执行其他长任务,也不要把这些工作全部塞进 onMessageReceived()。Firebase 官方建议,对可能超过几秒的处理应转交给 WorkManager 等合适的后台执行机制,否则可能因进程生命周期和后台限制导致任务被暂停或终止。([Firebase][5])

最后检查设备与网络链路

如果服务端发送成功、Token 有效,但多个测试设备都收不到,就把范围扩大到设备联网与通道基础设施。FCM 官方排障文档特别提示,防火墙可能限制 FCM 所需连接;文档列出的相关端口包括 5228、5229 和 5230。对于企业网络或受限 Wi-Fi 环境,这一步尤其重要。([Firebase][6])

单设备排查时可以先确认设备是否正常联网,再比较“Wi-Fi、移动网络、另一台设备”三组结果。若只有某类网络失败,问题范围通常已经从应用业务代码缩小到了网络出口、系统策略或厂商设备环境。

对于依赖厂商推送通道的设备,还要把“FCM 发送成功”和“厂商通道最终展示成功”分开记录。不同设备厂商可能存在自己的后台限制与通道状态,因此日志最好包含消息 ID、客户端 Token 标识、发送时间、客户端接收时间和 App 状态,而不是只记录一句“push failed”。

用证据把链路逐段闭合

最终可以把一次故障压缩成五个证据点:服务端响应、当前 Token、消息类型、客户端 App 状态、设备网络状态。其中任意一项没有证据,都不要直接下结论。

修复后的验收应至少覆盖“前台收到”“后台看到通知”和“Token 更新后仍能收到”三个场景;对于企业或厂商设备环境,再增加受限网络下的验证。这样验证的是完整推送链路,而不只是某一次发送请求返回成功。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

定位推送消息为什么收不到

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通