做Flutter安卓App的人基本都会在一个节点被“推送”卡住App上线了用户要收到订单提醒、审批通知、活动公告服务器总不能一直挂在后台轮询业务方还动不动来一句“怎么我手机收不到消息”。这篇文章要解决的就是把极光推送和本地通知在Flutter安卓端一起接好让“服务端下发的消息”和“本手机该弹的提醒”各司其职也把我在真实项目里踩过的坑一次性倒出来。Flutter接入极光推送这件事网上的教程大多是抄官方readme能跑到回调就已经算成功但真正在实际项目里跑通“远程推送触发本地通知、点击通知跳转指定页面、系统权限掉链子”这些组合场景还是有门槛的。这篇文章不只讲插件怎么初始化会把控制台配置、AndroidManifest、权限适配、通知渠道、路由跳转、常见坑位都拆开讲。适合准备上推送、或者已经在接推送但被线上用户反馈折磨的同学。1. 方案先想清楚极光推送和本地通知是什么分工1.1 远程推送解决“触达”本地通知解决“呈现”先分清两件事。极光推送解决的是“网络触达”它把服务端的消息通过极光的通道推到手机上本地通知解决的是“系统呈现”它让App在本地直接创建一条系统通知不经过任何网络。很多人接到一个需求“帮我接入推送”默认只有极光推送其实工程里往往还需要本地通知做配合否则你会在三个场景里寸步难行。第一个场景是App在前台想让通知样式统一或者不出系统通知只在应用内做提示第二个场景是定时提醒类需求比如吃药、还款、打卡这类任务根本不应该依赖服务端下发客户端本地排期就够了第三个场景是进程被系统杀掉后你想让App在下一次启动时根据本地缓存重新补发提醒远程推送这时候根本帮不上忙。这三个场景极光推送都替代不了本地通知它们是互补关系不是二选一。从技术链路看我的做法是服务端只负责决定“发什么内容、发给谁”极光SDK负责把消息送到设备客户端拿到消息后统一走一套“消息处理中心”该落库的落库、该弹通知的调用本地通知、该跳页面的带上payload去路由。如果收到的是极光自定义消息那就更简单了服务端不触发系统通知我完全用本地通知来控制展示时间和样式。这套思路的好处是把“消息传输”和“消息展示”彻底解耦后面不管是换极光还是换厂商通道客户端只需改接入层展示层完全不用动。1.2 为什么不自建长连接非要选极光自建推送通道这件事我劝你慎重除非团队有专门的IM基础设施。Android上自建长连接需要自己维护心跳保活、网络切换重连、各厂商的后台限制适配哪个都是大工程。极光这类专业推送服务已经把国内厂商的兼容性做好了虽然也不能保证进程被杀后100%送达但省下的运维成本是实打实的。选极光还有一个理由它跟厂商通道是打通的。你可以在极光控制台同时配置华为、小米、OPPO、vivo等厂商的密钥SDK在对应品牌的手机上会自动走厂商系统通道这在国产ROM上尤其关键——纯极光长连接在后台被杀后基本收不到但厂商通道作为系统级服务能活下来。如果你团队的业务主要面向国内安卓用户这个适配能力是绕不开的。1.3 先画一条推送数据流再动手写代码我习惯在接任何推送SDK之前先画清楚数据流避免后面改接口改到哭。标准的一条流向是这样的服务端调用极光REST API把通知或自定义消息推送给指定registrationId、别名或标签极光服务器把消息下发给设备上的JPush SDKSDK以系统通知形式展示或通过事件回调把原始数据交给Flutter层Flutter层拿到后决定是否用flutter_local_notifications重写通知样式同时把消息体转发给路由去跳转页面。点击事件又分两种路径用户点击的是极光SDK弹出的通知走的是极光的onOpenNotification回调用户点击的是我用本地通知弹出的通知走的是本地插件的onDidReceiveNotificationResponse回调。两条路径在Flutter端看起来像是两个入口但最终都要汇聚到同一个“根据通知类型跳转对应页面”的公共方法上。先把这个流程定下来后面写代码会非常顺。2. 环境准备与依赖选型接入前的硬性条件2.1 Flutter环境和Android项目基础配置接推送之前先把Android工程底子打好。我这里使用的Flutter版本是3.x稳定版compileSdk和targetSdk建议直接拉到Android 13或以上因为极光SDK新版本和flutter_local_notifications都开始强制要求较高的SDK版本太低会导致编译报错或者运行时权限异常。build.gradle里常见的坑是ndkVersion和abiFilters。极光SDK的so库包含多个ABI如果工程里为了减包只保留了arm64-v8a需要确保极光的aar也支持否则会在个别设备上崩。我用的是默认不限制ABI的方式然后用AGP的abiFilters统一裁剪实测对极光没有影响。工程结构上建议把推送相关代码单独抽成一个pkg至少不要全写在MainActivity里。原因很简单推送回调会贯穿整个App生命周期你得在冷启动、页面恢复、权限变化等各个状态都处理消息零散写在页面里后面维护成本极高。2.2 插件选型jpush_flutter和flutter_local_notifications极光官方维护的Flutter插件在pub.dev上是jpush_flutter这是接入远程推送的最直接选择。它的Android底层就是极光JPush SDK通过MethodChannel和EventChannel把原生事件抛给Dart层所以版本更新对我Flutter端来说是透明的只要关注它适配的JPush SDK版本即可。本地通知这边pub.dev上社区最活跃的是flutter_local_notifications它不只是Android能用iOS、macOS都覆盖而且支持定时通知和通知渠道管理算是本地通知的瑞士军刀。插件版本别乱选先去pub.dev看jpush_flutter最新版本号跟你的Flutter版本是否兼容。早期有些版本要求Flutter 2.x直接用在新项目上会出现找不到符号的编译错误。选定版本后记住两个插件的主版本锁定不要轻易升降级因为这两个插件都涉及原生层和Flutter层的通道协议升级一个往往要连带升级另一个否则事件回调会丢。2.3 AndroidManifest配置权限不是越多越好极光推送的完整权限列表很长但理解每个权限干什么比直接抄列表重要。基础的必须要INTERNET、ACCESS_NETWORK_STATE、WAKE_LOCK这是长连接和网络状态监听的基础VIBRATE和RECEIVE_USER_PRESENT用于通知震动和亮屏提醒如果你要处理开机后补发通知还需要RECEIVE_BOOT_COMPLETED。Android 13开始多了两个容易漏的权限本地通知必须申请POST_NOTIFICATIONS定时通知需要SCHEDULE_EXACT_ALARM。这些光写在AndroidManifest里还不够运行时也要申请后面第四章我会专门讲权限适配。极光SDK还要求在Manifest里声明一个自定义权限并用你的包名做后缀作用是防止其他应用伪造极光广播这个字段写错了会导致收不到推送。别为了权限精简把极光的receiver或service移除SDK的组件都需要在Manifest里显式声明。Manifest配置完成后务必检查你的applicationId和极光控制台的包名是否一致一个字母都不能差。包名不一致是收不到推送的第一大原因极光服务器按包名匹配应用你本地改了applicationId但控制台没改注册出来的registrationId在服务端下发时会直接失败。3. 极光推送接入实操从注册到消息回调3.1 极光控制台配置先搞定AppKey和包名代码层面动手前先去极光控制台注册应用。创建应用的时候会要求填写Android包名这一步填的包名必须和工程里applicationId完全一致。我当时在这个环节吃过亏控制台填了applicationId后面为了上架改了包名结果推送直接断掉所以在这里多提醒一句包名变更后极光控制台要同步改且AppKey是不变的。控制台里每个应用会分配一个AppKey这是初始化SDK的唯一凭证。同一套代码如果要在多个渠道包之间切换AppKey最好把AppKey放到启动配置里按渠道区分不要写死在代码里。Debug和Release如果使用不同AppKey注意检查混淆和BuildConfig的引用我见过有人把Debug的AppKey带上线推送一天就触发限流。3.2 Flutter端初始化避开重复初始化的坑初始化代码看起来简单但有个细节必须在runApp之前或第一个页面initState里完成而且整个进程生命周期只能调一次。我见过有人把初始化放在入口页的initState里页面被重建时又执行一遍导致极光SDK重复注册、事件回调被多次监听点击一条通知进来三个回调同时触发。推荐的写法是把初始化封装在一个独立的推送服务类里通过单例模式调用。初始化时可以开启debug模式这样可以打印极光SDK的注册日志排查问题会方便很多正式包再关掉。初始化成功后会通过回调拿到registrationId这个ID要上报给服务端服务端才能给你这个设备单独发推送它相当于设备在推送系统中的身份证。初始化完成后调用getRegistrationID获取设备标识但这个接口在冷启动时有概率返回空稳妥做法是把registrationId缓存到本地每次进入App时异步去极光获取并对比发现变化就重新上报服务端。别小看这个细节极光在某些场景下会自动换registrationId你不主动更新服务端发到你旧ID上就永远送达不了。3.3 事件回调Dart层的三个入口极光插件在Dart层暴露了三个核心回调分别对应通知到达、通知点击和自定义消息到达。onReceiveNotification对应SDK收到推送通知此时系统通知已经展示onOpenNotification对应用户点击通知栏是跳转页面的主要入口onReceiveMessage对应极光自定义消息这条消息不会由SDK自动展示完全由你决定怎么处理。这三个回调通过EventChannel源源不断传给Flutter所以如果你用了Provider、Bloc这类状态管理注意回调触发时组件树可能还没挂载完整直接用context要非常谨慎我在项目里是把消息写成全局状态等页面刷新时再读取。自定义消息的典型场景是“静默推送”比如App内聊天消息、图书更新的角标提示服务端用自定义消息下发客户端视情况决定是否通知用户这种模式最能体现极光本地通知的组合优势。代码骨架大概是这样的JPush.addEventHandler( onReceiveNotification: (MapString, dynamic msg) { // 收到通知msg里包含title、content、extras }, onOpenNotification: (MapString, dynamic msg) { // 用户点击了通知这里跳页面 }, onReceiveMessage: (MapString, dynamic msg) { // 收到自定义消息自己决定是否alert }, );我处理onOpenNotification时会先从extras里取业务类型type和目标id再查一遍本地缓存确认这条通知对应的业务数据是否已经存在如果不存在先跳详情骨架页并显示loading等接口返回再渲染。这么做是防止用户点击通知时网络还没恢复页面白屏。3.4 别名和标签让推送更精准的三板斧极光的别名和标签机制本质上是给设备和用户之间建映射。别名适合一对一场景比如用用户ID作为别名每个用户只能绑定一台设备标签适合一对多场景比如按版本、按用户层次、按活动分组推送。我实际的用法是用户登录成功后setAlias为用户ID退出登录时clearAlias避免下一个登录用户收到上一个用户的推送标签则按“登录用户”、“测试员”、“vip用户”这些粗粒度维度打方便运营圈选人群。设置别名和标签也有时序问题。用户登录成功、进入主页面这两个时机都可能有网络延迟千万别在setAlias后立刻调服务端“推送测试消息”极光的别名绑定是需要几秒生效的。我踩过这个坑测试时点了推送没反应以为代码错了其实是别名还没生效。出于稳妥设置别名成功后不要立即依赖它推送而是用registrationId先做联调等整个链路通了一次再切换到别名模式。4. 本地通知实现细节权限、渠道、定时与路由4.1 flutter_local_notifications初始化与通知渠道本地通知插件初始化的核心是InitializationSettings。Android端需要传一个AndroidInitializationSettings里面指定应用图标我使用的是mipmap/ic_launcher如果你的应用有专门的推送图标可以单独做一个小图标通知栏显示效果会好很多。初始化还有一个关键参数onDidReceiveNotificationResponse用户点击本地通知时触发。这个回调在冷启动和热启动的表现不同冷启动时App还没跑起来插件会把通知的payload存起来等初始化完成后回调热启动时直接回调。因此初始化代码必须在入口最早的地方执行并且要把收到的payload转发给统一路由处理否则会出现冷启动点击通知无法跳转的经典bug。通知渠道是Android 8.0引入的概念你可以把它理解成给不同类型的通知办“分类标签”。极光SDK默认会创建自己的渠道而flutter_local_notifications可以创建多个渠道比如订单消息、活动消息、系统消息各一个渠道。用户可以在系统设置里单独关闭某一类通知但如果不设置渠道所有通知混在一起用户只能全量关闭这对产品来说很伤。4.2 Android 13权限适配POST_NOTIFICATIONS绕不过去Android 13开始通知权限从安装时自动授权变成运行时权限这是本地通知最容易踩坑的点。很多用户手机升级到Android 13后突然收不到本地提醒原因就是没有主动请求POST_NOTIFICATIONS权限。对应到代码你需要使用flutter_local_notifications的resolvePlatformSpecificImplementation方法去拿Android实现然后调用requestNotificationsPermission。请求时机也讲究不要在App启动时就立刻弹权限用户会反感建议在第一次需要弹通知的时候再请求并且先通过isNotificationsEnabled判断当前是否有权限。在Android 13以下的设备上这个权限接口不会生效但也不会报错所以可以放心调用。极光SDK那边如果没适配Android 13它自己弹出的通知也会被系统静默丢弃升级极光SDK版本能解决一大半问题。4.3 定时通知时区与精确闹钟权限定时通知我重点说两个坑。第一个是时区flutter_local_notifications的zonedSchedule使用timezone包必须先在main函数里初始化时区tz.initializeTimeZones()并设置本地时区tz.local。如果你忘记设置时区Android默认用UTC你的“每天晚上9点提醒”可能变成“UTC时间上午9点提醒”下午才会弹用户直接懵。第二个坑是Android 12的精确闹钟权限。定时任务如果要求准点触发需要SCHEDULE_EXACT_ALARM权限但这个权限在Android 12上默认不授予用户需要手动去系统设置里开启“闹钟和提醒”。如果App只申请权限而不引导用户定时通知可能会被延迟不是不弹是弹得不准。如果你的业务对“准点”不敏感可以退一步用AndroidScheduleMode.inexactAllowWhileIdle避开高版本权限限制系统会在合适时间发出通知省电也省心。4.4 点击本地通知跳转页面payload与路由本地通知点击跳转的关键是把业务数据编码进payload。flutter_local_notifications的show和zonedSchedule都有payload参数我一般传一个JSON字符串包含type和id两个字段路由收到payload后解析类型再调对应页面。这样处理的优势是即使通知栏已经被系统清空只要用户点了未清除的那条依然能回到正确的页面。跳转还要区分业务深度。如果App进程冷启动Flutter的Navigator还没有任何页面直接push会崩我的做法是先等第一个页面(通常是启动页或主页)挂载完成然后再push目标页。判断冷启动可以用插件的getNotificationAppLaunchDetails方法它返回didNotificationLaunchApp字段App是被通知点击拉起的就为true。用法虽然多一层判断但能避免线上冷启动崩溃。5. 远程推送和本地通知的搭配实战5.1 前台通知服务端用自定义消息客户端接管展示最推荐的搭配模式是服务端对需要App前台处理的业务使用极光自定义消息而不是普通通知下发。自定义消息到了客户端不弹任何系统通知完全由我在onReceiveMessage里处理想弹本地通知就弹想走应用内横幅就走横幅发不发、怎么发都控制在自己手里。这样做的好处是前台逻辑完全可测不受系统通知展示时机影响。后台消息则仍然用极光普通通知依赖极光和厂商通道在进程存活的情况下弹出系统通知。这两种类型在极光控制台是分开发送的代码层面也只在一个回调里判断消息类型即可。这套模式跑起来后前台体验和后台送达率都照顾到了不会顾此失彼。5.2 离线兜底本地缓存加定时自查离线兜底针对的是“服务器想推但用户手机没网”的场景。极光在设备离线时会把通知存一段时间但用户恢复网络后是否还能收到取决于厂商通道和极光的策略没有100%保障。我自己的做法是对时效性要求高的业务在客户端本地维护一份“待提醒队列”每次App进入前台或网络恢复时拉取服务端未读消息接口然后根据业务规则重新生成本地通知。这样即使极光通道因厂商限制丢了消息用户打开App时也能通过接口补偿收到通知体验不会断。要注意的是兜底通知要加去重逻辑避免用户已经读过消息又被通知提醒一次我是在本地用消息ID做去重收到通知前先查一下是否已处理过。5.3 多渠道分组与用户偏好设置如果项目里有多种业务通知强烈建议在设置页里提供通知偏好开关做这件事情并不复杂核心就是借助Android通知渠道。用户设置页面里展示“订单通知”“活动通知”“系统通知”三个开关每个开关对应一个channelId关闭开关时调用flutter_local_notifications或原生方法去停用对应渠道。极光自带的系统通知渠道默认可能开着用户关掉我的自定义渠道并不影响极光渠道的通知所以如果需要统一开关最好所有远程通知都通过自定义消息下发然后用本地通知统一走flutter_local_notifications的渠道管理。这种模式下通知的最终展示权完全从极光手里收到了自己手里产品和运营也能更灵活地调整通知策略。6. 常见问题速查与排障实录6.1 收不到推送先按链路排查而不是问文档收不到推送是最高频问题我排障时按顺序查五步第一步看极光控制台推送记录确认消息是否成功下发第二步看客户端Logcat里JPush的关键日志确认SDK是否注册成功第三步核对AppKey和包名第四步看手机是否在厂商白名单限制下第五步看通知权限是否关闭。五步走完90%的问题都能定位。其中注册成功与否最重要Logcat里会打印registrationId相关信息。如果完全没看到极光日志多半是Manifest里receiver被裁剪了或者插件初始化没执行。注意使用混淆时极光SDK要添加keep规则proguard-rules.pro里保留cn.jpush包否则SDK的反射调用全军覆没。还有个小细节安卓虚拟机怎么联网这是很多人在模拟器上测试收不到通知的原因。模拟器的网络模式要选桥接或共享模式并确认SDK能访问公网接口测试机的推送网络环境和生产环境不一致优先用真机验证推送时序模拟器只用来验证UI。6.2 点击通知没有跳转页面点击通知没反应一般先区分是哪条通知。极光的通知点击走onOpenNotification本地通知点击走onDidReceiveNotificationResponse两边要分别加日志确认回调有没有触发。如果回调触发了但没跳转检查冷启动时Navigator状态如果回调都没触发多半是回调注册太晚Post了初始化时机。本地通知冷启动点击还有一个特殊场景如果App在通知被点击时才被拉起插件的getNotificationAppLaunchDetails会在初始化时才返回详情如果你在main函数顶层就急着做路由跳转页面还没就绪就会失败。处理办法是把点击事件的业务数据先放入一个全局单例等首个页面build完成后统一调度跳转。总结成一张速查表问题现象常见原因处理办法收不到远程推送AppKey或包名不一致核对控制台配置收不到远程推送厂商通道未配置按机型接厂商推送通知不弹Android 13未授权通知请求POST_NOTIFICATIONS定时通知不准时未设置时区初始化tz本地时区定时通知不弹Android 12精确闹钟被限制降级非精确模式或引导授权点击通知无反应回调注册时序不对确保init期间已注册回调6.3 本地通知在国产ROM上不弹国产ROM对后台限制比原生Android激进得多华为、小米、OPPO、vivo都有自己的省电策略和自启动管理。App不在白名单里本地通知的定时任务可能被系统冻结极光通知也可能延迟这是当前国内安卓推送环节的最大难题。解决思路分两层基础层是申请厂商推送通道让通知走系统级通道这是官方推荐方案兜底层是在App进程被杀后下一次启动时通过自查补偿。别指望改客户端的保活代码来对抗厂商限制现在的高版本系统上任何保活手段都不可持续还是老老实实按厂商规则来。6.4 抓包失败和日志调试技巧调试极光推送时很多人想抓包看请求内容但极光SDK做了TLS通信加密抓包工具经常只能看到握手失败这个现象是正常的不代表推送链路有问题。与其纠结抓包不如直接看Logcat过滤JPush关键字SDK会把注册、连接状态、消息到达都打出来信息量足够。另一个技巧是用极光控制台给指定registrationId发测试推送这样确认了服务端到设备的链路没问题再回头查自己Flutter端的逻辑。如果连推送记录都显示成功但设备没反应那基本可以锁定是Manifest或权限问题回到6.1的五步法逐项排查即可。实际项目里踩过几次坑之后我最大的体会是推送这个功能表面上是接SDK本质上是在做Android系统机制的适配。极光负责把消息送到门口能不能进用户的眼睛取决于权限、渠道、厂商限制这些底层细节。如果文章里只选一条建议带走那就是把“消息接收”和“通知展示”分开设计远程推送只管传输本地通知负责打磨展示逻辑这个分层能让你在后续换厂商、换推送服务商时少挖好几个坑。最后再分享一个小技巧推送相关的所有关键日志上线时不要全清空保留一个可动态开启的debug日志入口线上用户反馈收不到消息时让他发一份日志排查效率比你远程盲猜高一倍不止。