原生移动开发 / 系统课时
定位推送消息为什么收不到
定位推送消息为什么收不到
推送收不到时,最有效的方法不是反复点“发送测试”,而是沿着消息链路逐段确认:服务端有没有成功提交、目标 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> 都是占位符,实际值可能不同。
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": "推送链路验证"
}
}
}'预期结果
成功时: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 应用上下文中运行。
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)}...")
}
}预期结果
成功: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 更新后仍能收到”三个场景;对于企业或厂商设备环境,再增加受限网络下的验证。这样验证的是完整推送链路,而不只是某一次发送请求返回成功。