1. 离线推送到底在解决什么问题做移动端应用的人迟早会撞上这个需求用户把App划掉了、手机锁屏了、后台进程被系统回收了这时候业务侧发出一条通知用户还能不能在通知栏看到答案就是离线推送要解决的核心命题。uniPush这套方案本质上是在uni-app生态里把各家手机厂商的推送通道统一封装了一层让开发者不用分别去对接多个厂商的SDK就能实现“应用未运行也能收到通知”的效果。我接触这个需求是在一个订单提醒场景里。业务方的诉求很直接用户下单后商家端要能实时收到新订单提示哪怕商家把App切到后台甚至清理掉了也得弹出来。在线推送好办长连接活着就行难的是离线——App进程都没了长连接自然断了这时候只能靠系统级的推送通道把消息递到设备上。这就是离线推送存在的意义也是它比在线推送复杂得多的原因。这篇文章适合两类人看一类是刚接触uni-app、准备接入推送功能的新手需要一份能照着走的完整流程另一类是做了一段时间、在线推送跑通了但离线一直不生效、被各种厂商配置绕晕的开发者。我会把整个链路的原理、配置、踩坑点拆开讲尽量让不同基础的人都能对上号。先说清楚一个前提认知离线推送不是uniPush自己“推”过去的它只是帮你把消息转发给各家厂商的推送服务真正把通知弹到用户手机上的是手机厂商的系统通道。理解这一点后面很多配置为什么必须做、为什么必须去厂商后台操作就顺理成章了。2. 推送链路的整体设计与方案选型2.1 在线推送与离线推送的分工逻辑很多人一开始会把在线和离线混为一谈觉得“我调了推送接口消息就该到”。实际上这两条链路是分开的。在线推送走的是uniPush自己维护的长连接通道App进程活着、连接没断消息通过这条通道直达客户端速度快、格式自由、能携带自定义数据。离线推送走的是厂商通道消息先到厂商的推送服务器再由厂商的系统服务投递到设备App不需要运行。系统在判断走哪条路时逻辑大致是先看设备上App的长连接是否在线在线就走在线通道不在线就查这个设备有没有绑定厂商推送标识比如某厂商的推送token有就走对应厂商通道如果厂商通道也没配那这条消息基本就丢了用户什么也收不到。所以离线推送能不能成关键看厂商通道有没有配通。这里有个容易忽略的点在线和离线不是二选一而是互补。你不可能指望离线通道做到秒级到达厂商通道有它自己的调度节奏延迟从几百毫秒到几秒都正常。所以对实时性要求极高的场景在线通道仍然是主力离线通道是兜底。2.2 为什么必须走厂商通道而不是自建长连接有人会问既然长连接能推消息为什么不让App常驻后台保持连接原因在于系统对后台进程的管理越来越严。设备为了省电会在息屏一段时间后冻结甚至杀掉后台进程长连接自然就断了。你就算用各种保活手段在主流系统上也会被限制得很死而且保活本身会带来耗电、被用户投诉、被系统判定为异常应用等一堆问题。厂商通道是系统亲儿子它由操作系统自己的推送服务负责投递不受后台进程限制也不需要App常驻。这是唯一稳定可靠的离线方案。代价就是你必须按各家厂商的规矩来去各自的开发者后台注册应用、申请推送权限、配置证书或密钥然后把这些信息填到uniPush的后台里。2.3 uniPush的封装价值在哪里如果不用uniPush你得分别集成多个厂商的推送SDK每个SDK的初始化方式、消息格式、回调接口都不一样维护成本极高。uniPush做的是抽象层你在一个后台配置好各厂商的参数客户端用统一的API获取推送标识服务端用统一的接口发消息剩下的分发逻辑由uniPush处理。对中小团队来说这能省掉大量对接和调试时间。不过要清醒认识到封装不等于免配置。厂商后台该注册的还得注册该填的包名、签名、密钥一个都不能少。uniPush只是把“调用”这一步统一了“配置”这一步还是得你自己跑一遍。我见过不少人以为用了uniPush就万事大吉结果离线一直不通最后发现是厂商后台根本没配。3. 核心配置细节与实操要点3.1 厂商后台注册的关键参数每个厂商的后台都要填一堆信息其中最容易出错的是应用包名和签名。包名必须和你在项目里配置的完全一致一个字符都不能差大小写敏感。签名指的是应用签名证书的指纹通常需要填SHA1或SHA256。如果你用的是调试签名那正式打包后签名变了推送就会失效——这是新手最常踩的坑之一。获取签名指纹的方法一般是用keytool命令对签名文件做处理。这里要注意不同厂商要求的指纹格式可能不同有的要带冒号分隔有的不要填之前一定看清楚后台的提示。我建议把调试签名和正式签名的指纹都记录下来配置时对号入座避免上线后才发现推不通。配置项常见要求易错点应用包名与项目manifest一致大小写、多段包名写错签名指纹SHA1或SHA256调试/正式签名混用应用密钥厂商后台生成复制时带空格推送开关后台手动开启忘记开启导致静默失败3.2 客户端初始化与标识获取客户端这边核心是拿到设备的推送标识clientid并上报给业务服务端。这个标识是uniPush分配的设备唯一标识服务端发消息时靠它定位目标设备。获取标识的时机很关键要在推送模块初始化完成之后再去取否则可能拿到空值。初始化一般放在应用启动的早期阶段但要注意不能阻塞主流程。我的做法是在应用启动后异步初始化推送模块初始化成功的回调里再去获取clientid然后上报。如果获取失败要有重试机制因为首次启动时网络或权限问题都可能导致失败。还有一个细节用户卸载重装App后clientid会变。所以服务端不能把clientid当成永久标识存死要允许更新。业务上通常会把clientid和用户账号做绑定用户换设备或重装后重新绑定即可。3.3 通知权限与系统设置离线推送要弹出通知前提是用户授予了通知权限。现在主流系统对通知权限的管理越来越细有的默认关闭有的会分级比如允许通知但不允许横幅。如果用户关了通知权限你推过去的消息会被系统静默丢弃服务端可能还显示发送成功这就很坑。所以客户端要在合适的时机引导用户开启通知权限比如首次进入消息相关页面时用友好的方式说明为什么需要通知。不要一上来就弹系统权限框用户很容易拒绝。另外要提供入口让用户能跳转到系统设置里手动开启因为一旦拒绝过再次请求系统框可能就不弹了。提示通知权限被关闭时部分厂商通道仍会返回发送成功但用户实际收不到。排查离线问题时先确认目标设备的通知权限状态。4. 完整实操流程与关键环节实现4.1 从零到跑通的完整步骤我把整个接入流程梳理成一条线照着走基本能跑通。第一步在uni-app项目里开通uniPush模块这一步在项目的manifest配置里操作勾选推送相关选项。第二步登录uniPush的开发者后台创建应用并拿到AppID等信息。第三步逐个去各厂商的开发者后台注册应用把包名、签名、密钥填好拿到厂商侧的推送参数。第四步把这些厂商参数回填到uniPush后台对应的配置项里。第五步客户端集成推送模块初始化并获取clientid。第六步服务端调用推送接口指定目标clientid发消息。第七步真机测试分别验证在线和离线两种状态。这七步里第三、四步是最耗时的因为厂商后台的界面和术语各不相同。建议一次只配一个厂商配完就测通了再配下一个不要一口气全配完再测否则出问题很难定位是哪个环节。4.2 服务端发送消息的参数构造服务端发消息时要区分通知消息和透传消息。通知消息由系统通道直接展示在通知栏用户点击后打开App透传消息则是把数据交给App自己处理App不在线时透传消息可能收不到或延迟很久。做离线提醒一般用通知消息因为只有通知消息才能保证在App不运行时也弹出来。构造消息时标题和内容要简洁明确因为通知栏展示空间有限。点击后的跳转行为要配置好通常是打开App并跳转到指定页面页面路径通过附加参数传递。这里要注意不同厂商对附加参数的长度和格式有限制太长的自定义数据可能被截断重要信息尽量精简。// 服务端推送请求的示意结构伪代码具体字段以官方文档为准 { clientid: 目标设备的推送标识, title: 您有一笔新订单, content: 订单号 12345请及时处理, payload: { page: /pages/order/detail, orderId: 12345 } }4.3 真机测试的验证方法测试离线推送不能只在模拟器上跑必须用真机。验证步骤是先在App里确认clientid已经获取并上报然后把App从后台彻底划掉确保进程被杀。接着在服务端发一条推送观察手机通知栏是否弹出。如果弹出了点击看是否能正确跳转。如果没弹出按这个顺序排查先确认设备通知权限是否开启再确认厂商通道配置是否正确包名、签名然后看服务端返回的推送结果里有没有报错信息最后确认设备是否真的处于离线状态有时候App被系统缓存着其实还在线。我习惯在测试时把App的在线状态和离线状态分别测一遍确保两条链路都通。注意部分系统在App被划掉后短时间内仍可能通过在线通道收到消息这会干扰你对离线通道的判断。测试离线时最好等待一两分钟或者重启设备后再测。5. 常见问题与排查技巧实录5.1 离线推送不生效的排查顺序离线推送不通是最常见的问题我总结了一套排查顺序基本能覆盖八成情况。第一查通知权限这是最容易被忽略的。第二查厂商后台配置重点看包名和签名是否和当前安装的包一致。第三查uniPush后台的厂商参数是否填对有没有复制错。第四查服务端发送时用的clientid是不是当前设备的。第五查厂商通道本身是否正常有时候是厂商服务临时波动。这套顺序的逻辑是从客户端到服务端、从本地到远端逐层排除。很多人一上来就怀疑服务端代码其实大部分问题出在配置和权限上。现象可能原因排查方向完全收不到通知权限关闭检查系统通知设置完全收不到厂商参数错误核对包名签名密钥在线能收离线不能厂商通道未配通检查厂商后台配置部分设备收不到设备标识失效重新获取并上报clientid延迟很久才到厂商调度策略属正常现象非故障5.2 签名与包名不一致的隐蔽问题签名不一致这个问题特别隐蔽因为它在开发阶段可能完全正常一到正式打包就失效。原因是开发时用的是调试签名厂商后台填的也是调试签名的指纹测试通过。但正式发布用的是正式签名指纹变了厂商通道校验不通过推送就被拒了。解决办法是在厂商后台同时配置调试和正式两套签名或者干脆在开发阶段就用正式签名调试。我个人的习惯是项目一开始就配好正式签名避免后期切换带来的麻烦。另外如果用了多渠道打包每个渠道的签名如果不同也要分别配置。5.3 消息被系统拦截或折叠的情况有时候推送发出去了厂商也返回成功但用户就是没看到。这可能是被系统拦截或折叠了。现在很多系统会对通知做智能分类营销类消息可能被折叠到“不重要”分组里用户不展开就看不到。还有的系统对高频推送有限制短时间内推太多会被限流。应对办法是控制推送频率别把用户当轰炸对象。消息内容要真实有价值避免被系统判定为垃圾通知。如果业务上确实需要高频提醒考虑用其他方式补充比如应用内的红点或角标。另外部分厂商支持设置通知的重要级别把关键消息设为高优先级能降低被折叠的概率。5.4 用户重装或换设备后的标识处理用户卸载重装后clientid会变如果服务端还拿旧的clientid发消息自然推不到。所以服务端要设计好标识更新机制App每次启动获取到clientid后都和当前登录账号做一次绑定更新覆盖旧值。这样即使用户换了设备只要重新登录绑定关系就更新了。还有一种情况是用户换了手机但没换账号新设备登录后会上报新的clientid服务端更新绑定即可。要注意的是一个账号可能同时绑定多个设备比如手机和平板如果业务需要给所有设备推送就要存多个clientid如果只推最近活跃的设备就存最新的一个。这个策略要在业务层面想清楚。6. 提升到达率的几个实战经验6.1 合理设置推送时机与频率推送到达率不只是技术问题也和推送策略有关。系统会对频繁推送的应用做限制推得越猛被限流的概率越高。我的经验是把非紧急的消息合并推送比如把多条订单提醒聚合成一条“您有3笔新订单”而不是一条一条推。这样既减少了推送次数用户体验也更好。时机上避开用户休息时段除非是紧急业务。有些系统会根据用户的使用习惯决定是否展示通知长期在深夜推送的应用可能被降低优先级。这些细节看起来和代码无关但直接影响到达率。6.2 多厂商通道的覆盖策略不同厂商的通道覆盖不同的设备理论上要把主流厂商都配上才能覆盖大部分用户。但配置多个通道意味着维护成本上升每个厂商的后台都要盯着。我的建议是优先配置用户量大的厂商通道根据自己应用的用户设备分布来决定优先级。配置多个通道后uniPush会根据设备品牌自动选择对应通道不需要你手动判断。但要注意某些设备可能同时支持多个通道实际走哪个由系统决定你无法强制指定。所以测试时要在不同品牌的设备上分别验证。6.3 监控推送结果与异常告警服务端发送推送后要记录发送结果包括成功、失败、错误码。厂商通道返回的错误码能帮你快速定位问题比如签名错误、参数缺失、设备无效等。建议把这些结果落库定期分析失败率发现异常及时告警。我一般会做一个简单的监控看板展示每天的推送量、成功率、主要错误码分布。这样一旦某个厂商通道出问题能第一时间发现而不是等用户投诉才知道。推送这种功能用户不反馈不代表没问题很可能消息丢了用户也不知道。7. 我踩过的几个坑和对应解法第一个坑是以为配了uniPush就不用管厂商后台。结果离线一直不通查了半天才发现厂商后台压根没注册应用。这个认知偏差很普遍记住uniPush是转发层厂商通道才是投递层。第二个坑是签名指纹填错。当时复制指纹时多带了一个空格肉眼看不出来排查了很久。后来养成习惯填完参数后用工具校验一遍或者直接粘贴后手动检查首尾字符。第三个坑是测试时用模拟器。模拟器没有真实的厂商推送服务离线推送根本测不了。必须用真机而且最好是主流品牌的真机覆盖不同厂商通道。第四个坑是忽略了通知权限。有次测试一直收不到最后发现是测试机的通知权限被关了。从那以后排查离线问题的第一步永远是看通知权限。第五个坑是clientid没及时更新。用户重装后服务端还用旧标识推了个寂寞。后来在启动流程里加了强制更新逻辑每次启动都重新绑定问题就没了。这些坑说起来都不复杂但每一个都真实消耗过时间。推送这东西配置环节多、涉及方多任何一个环节掉链子都会导致最终不通。所以我的建议是配一个测一个别贪快出问题按链路顺序排查别乱猜把配置参数文档化方便后续维护和交接。