FCM Mobile推送通知实战指南

最近项目里要接推送，折腾了好几天 FCM Mobile，从 Firebase 后台建项目到客户端收消息，中间踩了不少坑。这篇文章就把整个流程捋一遍，包括后台配置、Android 端集成、服务端下发，还有一些调试时容易卡住的地方。如果你也在搞 FCM Mobile 推送，照着走能省不少时间。

Firebase 后台到底要配哪些东西

先说要准备啥。去 Firebase 控制台新建项目，这个没啥难度。关键是后面加 Android 应用的时候，包名一定要和你的项目一致，不然后面 google-services.json 放进去也白搭。我第一回就是包名写错了，折腾半天收不到消息。

下载下来的 google-services.json 放到 app 目录下，然后在项目级 build.gradle 里加 classpath，app 级 build.gradle 里加 apply plugin。注意现在新版本 Firebase 用的是 BoM 方式，版本号让 BoM 统一管理就行，别自己一个个写版本，容易冲突。

还有一点，FCM Mobile 的服务端密钥在项目设置里的云消息传递标签页，那个旧版服务器密钥和新版 API 密钥不一样，服务端下发的时候用哪个要搞清楚。我一开始用错了密钥，一直报 401，查了半天才发现。

Android 端集成与收消息

客户端这边，先加依赖。implementation 里把 firebase-messaging 加进去，然后写一个继承 FirebaseMessagingService 的类，重写 onMessageReceived 和 onNewToken。onMessageReceived 是收前台和后台消息用的，onNewToken 是拿设备 token 的。

这里有个特别容易搞混的点：通知消息和数据的区别。如果你从控制台发的是通知消息，应用在后台的时候，通知会直接进系统托盘，onMessageReceived 根本不走。只有数据消息才会走 onMessageReceived。所以你要是想自己处理通知样式，就得发数据消息，或者后台发通知加数据混合的。

获取 token 用 FirebaseMessaging.getInstance().getToken()，这个 token 就是 FCM Mobile 用来定位设备的唯一标识。拿到之后要传到你们自己服务端存起来，后面下发就靠它。token 会变，所以 onNewToken 里也要更新。

还有个坑，Android 13 以后通知权限要动态申请，POST_NOTIFICATIONS 这个权限不申请的话，通知根本不显示。我测试机是 Android 12，没这个问题，换到 13 的机器上就懵了，后来才想起来权限没加。

服务端下发消息怎么搞

服务端下发有两种方式，一种是旧的 Legacy API，用服务器密钥，现在官方已经不推荐了。另一种是 HTTP v1 API，用 OAuth2 的 access token，更安全也更规范。建议直接用 v1。

v1 的接口地址是 https://fcm.googleapis.com/v1/projects/你的项目ID/messages:send，请求头里 Authorization 放 Bearer 加 access token。body 里写 message 对象，token 填设备的 FCM token，notification 里放标题和内容，data 里放自定义键值对。

如果你要批量发，可以用 topic 或者 condition。topic 就是让客户端订阅一个主题，服务端往主题发，所有订阅的设备都能收到。这个适合做群发，比如新闻推送。不过 topic 消息不能保证实时，有时候会延迟几秒。

调试的时候建议先用 Postman 或者 curl 试一下，确认服务端能发出去，再去看客户端为啥收不到。我一般先在 Postman 里发一条，看返回是不是 200，不是的话看错误信息，一般是 token 失效或者密钥不对。

常见问题与排查思路

收不到消息先看三点：google-services.json 有没有放对位置、包名有没有匹配、设备有没有装 Google Play 服务。国内很多手机没有 GMS，FCM Mobile 根本用不了，这个得提前确认。模拟器的话要用带 Google APIs 的镜像。

如果日志里看到 token 获取失败，检查一下网络和 Firebase 初始化。初始化可以用 FirebaseApp.initializeApp(context) 手动调一下，确保在获取 token 之前已经初始化完成。

还有，FCM Mobile 的消息默认是折叠的，同一条 collapse key 的消息会覆盖。如果你不想覆盖，每次发的时候换个 collapse key，或者不设置。这个在做聊天推送的时候要注意，不然用户只看到最后一条。

差不多就这些，FCM Mobile 整体不算复杂，就是细节多。把后台配置、客户端集成、服务端下发这三块跑通，基本就能用了。遇到问题多看日志，Firebase 的日志还是挺详细的，能帮你定位到具体哪一步出错。