★ FEATURED ARTICLE 聊一个我最近一直在折腾的项目Uniapp 框架里面的消息推送与热更新。这两个能力看起来一个管“触达用户”、一个管“更新代码”八竿子打不着但实际做起来你会发现它们就是跨端 App 后台运营的核心两条腿缺一条都跑不顺畅。这篇笔记是我从零梳理 UniPush、厂商通道、离线推送、wgt 资源包、版本升级链路这些知识点的完整记录里面有不少我真正踩过的坑和调通后的理解应该能帮你少走一点弯路。先说清楚这篇笔记能解决什么问题如果你正在用 Uniapp 做一款 Android 和 iOS 跨平台 App想实现“App 关闭后还能收到通知”“不让用户去商店更新也能修复线上 bug”这类需求这篇文章就是给你写的。我尽可能把推送的原理、厂商配置的流程、热更新的包制作与版本判断逻辑讲成人话版本想把这块搞明白的开发者、独立开发者、小团队前端都可以直接照着做。1. 先说结论Uniapp项目中推送与热更新的真实定位1.1 我为什么要把两者放在一起学我在做“跨平台系统”这个模拟项目时最开始的理解是推送就是发一条通知热更新就是换一下包。但真上手之后才发现这俩根本不是两个孤立的“工具”而是同一套“客户端-云端控制链路”的两端。推送要解决的是“用户没打开 App 时怎么触达你”热更新要解决的是“用户手上的旧版本代码怎么被新版本替换”。它们共同依赖一个事实你的 App 没有永远可靠的在线长连接也没有永远不变的版本。你必须在用户设备的系统通道、服务端的版本接口和客户端的资源文件之间维护好状态。所以我把它们放在一起学习原因有三个第一它们都涉及客户端与服务端的双向沟通推送消息的下发和升级包的检查本质上都依赖一个稳定的服务端响应第二它们都绕不开设备厂商差异Android 生态下不同厂商对推送进程和资源包安装的限制完全不一样这种“碎片化体验”是跨端开发绕不开的痛点第三它们在代码层面的表现都是异步回调推送离线消息和热更包的下载都会在 App 重新启动时触发连锁逻辑处理不好就会出现顺序问题。1.2 这篇笔记适合谁来读如果你是移动端新手你可以从这篇文章里拿到一套完整的推送与热更新落地方案包括后台怎么配、代码怎么写、测试怎么跑如果你是有跨端项目经验的开发者你可以在我的实操记录里找到一些常见的坑比如厂商通道审核为什么一直不通过、wgt 包为什么手机上安装失败、版本号为什么迟迟检测不到更新如果你是独立开发者我更建议你把这份笔记当成一份检查清单每次发版之前照着过一遍能省下大量和用户解释“我没收到通知”的时间。先说这么多下面直接进入推送的技术细节。2. 消息推送从方案选型到真正触达用户2.1 先理清楚Uniapp推送的几条路很多人在 Uniapp 项目里做推送第一反应是找第三方推送 SDK比如某极光、某友盟。这类方案本身没问题但它们和 Uniapp 的契合度、厂商通道的集成方式、消息透传的接口都要额外处理一段。我当时做项目时采用了一个更贴合框架的方案基于 Uniapp 官方推送模块来做也就是 UniPush。它和框架天然绑定能在 HBuilderX 里直接拿到推送权限同时最终会走系统的离线通道。这对跨端项目来说省掉了很多自己封装接口的麻烦。当然也要知道它的边界UniPush 本质上是一个推送服务它负责把消息从服务端推给用户设备但真正在 App 离线时让消息到达背后依靠的是厂商系统级推送通道。所以 UniPush 并不能绕开“必须去某个安卓大厂开放平台申请推送服务”这件事。更直接的对比是这样的方案优点缺点适合场景UniPush官方推送与框架深度整合离线走厂商通道免去自建通道厂商平台配置复杂调试链路长大部分 Uniapp 跨端项目第三方推送 SDK接口统一后台功能多需集成插件个性化需求受限不想碰厂商配置的团队自建长连接完全可控不走系统通知耗电、被杀、维护成本高对推送实时性要求极高的 App我当时的选择是 UniPush 为主、第三方为辅真实原因是 UniPush 的离线消息覆盖能力比自建长连接稳定太多了。自建长连接在 App 被系统回收之后基本失效很多国内安卓系统对后台进程的清理比你想的激进得多没有系统通道兜底推送就变成“用户打开 App 才收得到消息”。2.2 UniPush的厂商通道原理与配置要点先补一个核心概念厂商通道。起因是安卓系统不允许 App 自己常驻后台做长连接推送否则会被系统清理、耗电增加。但各个大厂有自己的系统级推送服务它们可以在 App 被杀后由系统消息中心替你收消息。UniPush 做的事就是把你的消息同时发到这些厂商的推送服务器再由它们推给用户手机的系统通知栏。你的 App 在线时消息可以直接通过长连接到达离线时消息走厂商通道到达。所以配置的第一步是去各大厂商开放平台注册应用并申请推送服务。这里有几个我实测中印象很深的差异厂商 A应用审核最严格往往要求你上传应用商店的下载链接和隐私说明很多个人开发者的应用还没有上架就被卡住了。它的推送服务配置里还有一个“自查域名”的流程必须等审核通过才能在 UniPush 后台拉到对应配置。厂商 B推送权限和分类审核相对快一些但对通知消息的条数有限制如果同一用户短时间收到太多推送部分推送会直接被系统折叠甚至丢弃。厂商 C对应用的目标版本有要求新版本系统要求适配某种后台启动限制如果版本太老离线消息到了也显示不出来。把这些厂商报备信息填到 UniPush 后台后还需要把每个厂商提供的 appkey / appid /密钥信息逐项填进 manifest 的 UniPush 节点再重新打包才生效。这里最容易踩的坑是填错 appid 或者漏掉某个厂商的密钥结果就是“部分手机收不到、部分手机能收到”。排查的时候一定要先把厂商配置逐项核对一遍再做真机测试。2.3 通知消息与透传消息的正确打开方式UniPush 下发消息有两种格式一个是通知消息一个是透传消息。理解它们的差别特别重要通知消息直接由系统在通知栏展示用户点击后才唤起你的 App。这种消息几乎不需要写代码配置完标题和内容就行问题是它的点击行为和业务参数传递需要额外封装。透传消息透传消息到达客户端时要走回调方法由你们自己的代码决定怎么处理比如弹窗、跳转、静默更新本地数据等。我实际项目中的经验是业务消息尽量走透传因为你可以做主流程控制。举一个非常常见的场景用户下单成功 30 分钟后未支付想发一个“催付通知”。这个通知要带上订单 ID用户点击通知后App 应该直接打开订单详情页。如果用透传消息在回调里拿到订单 ID 就能直接跳页面非常自然如果用通知消息还需要在点击回调里解析系统通知里塞的 extra逻辑会绕一点。我推荐的消息 payload 结构长这样{ type: order_payment_remind, title: 你有待支付订单, content: 距离关闭还有 15 分钟请尽快支付, data: { orderId: 202506170001 }, notifyType: transparent }这里的“type”是给客户端判断业务用的“notifyType”是让 UniPush 判断走通知还是透传的。实际开发时不要把大量业务字段塞在 title 和 content 里尽量放 data 字段方便后续扩展。2.4 消息推送的调试与验证方法调试推送时最容易出现“后台明明发了消息手机怎么都不响”的情况。我的经验是分三部分排查第一看客户端有没有在线推送回调。在 HBuilderX 里把 App 跑到真机打开推送的在线接收监听如果在线都收不到说明长连接或 appid 配置有问题优先检查 manifest 里的推送参数和打包权限第二看后台推送记录。UniPush 后台有“推送历史”可以看到一条消息实际推给了多少设备、成功多少、失败多少如果失败数很高很可能设备已经走厂商通道但厂商临时拒绝第三看厂商平台的推送统计数据它们能看到更细的设备级错误码。此外我强烈建议准备一台专门测试推送的手机不要用模拟器模拟器根本验证不了厂商通道。测试时把 App 从前台切到后台、再强制杀掉进程分别观察通知能不能送达。很多问题只有杀掉进程后才暴露出来比如厂商权限没配好、长连接被回收后没有走离线通道。3. 热更新机制资源包与版本链路的完整理解3.1 热更新到底能更新什么推送聊完进入另一个重头戏热更新。在我整理这块内容的时候最大收获是搞清了一个边界——热更新并不是万能的它只能替换 App 内的“非原生代码资源”。用 Uniapp 开发 App 时最终运行包里面既有原生壳的代码也有通过 JS 层编译出来的页面和逻辑资源。热更新能做的是把原来的 JS 资源替换成新版本比如修改页面样式、调整业务逻辑、修 bug。它不能更新的是原生插件、原生 SDK、以及任何需要重新编译 Android/iOS 包才能生效的改动。比如你集成了一个原生支付 SDK想升级 SDK 版本这就不能靠热更新解决必须走常规发版。我遇到过最经典的误区以为改成“所有代码都能热更”于是把原生插件相关的修改也塞进热更包结果用户端不生效白折腾。所以第一步就是明确热更包只包含 JS、页面结构、图片资源、部分配置凡是涉及原生能力的都另走发版流程。3.2 wgt资源包的制作与发布完整流程热更新不是发一个 apk 或 ipa而是发一个关于 Uniapp 的“资源升级包”也就是扩展名是 wgt 的资源包。它的制作流程非常固定第一步在 manifest.json 的“App 常用其他设置”里配好“原生App资源版本号”比如 1.0.0。这个版本号是整个热更新判断的关键客户端会拿着它与服务端返回的版本号做对比。第二步在 HBuilderX 菜单栏选择“发行 → 原生App-制作wgt资源包”编译完成后会生成一个 wgt 文件。需要注意这个文件和正式打包 apk 不同它只含资源不含原生壳。第三步把这个 wgt 文件上传到你自己的服务器或静态资源存储位置生成一个可以下载的地址同时在你服务端维护一个升级配置接口返回最新资源版本号和下载地址。第四步客户端在自己启动或进入指定页面时请求升级接口如果服务端返回的版本号比本地的新就下载 wgt 并执行安装。实际操作中的几个细节wgt 文件实际上就是一个 zip 包你甚至可以把后缀改成 zip 解压出来看内容它应该完整保留 App 的资源目录结构如果目录结构不对安装就会失败。另外要留意某些 Android 系统对安装包来源的限制如果用户禁止了“允许安装未知来源应用”wgt 的覆盖安装会失败需要在业务层做好提示。我用一个简单表格总结一下制作流程阶段操作关键点编译修改 manifest 资源版本号版本号不能比线上低打包HBuilderX → 发行 → 制作wgt资源包确认输出目录上传放到静态服务器/CDN记录下载地址发布服务端升级配置返回新版本号控制灰度/强制覆盖安装客户端下载 wgt 并安装注意目录结构与安装来源权限3.3 版本号管理与更新触发条件热更新的核心其实在“版本号”。这里的版本号有两个一个是 App 整体版本号也就是用户在应用商店看到的版本例如 2.3.0另一个是资源版本号比如 1.0.0。资源版本号可以独立于 App 版本号变化。日常发版逻辑通常是这样改一行页面文案 → 资源版本号从 1.0.0 变到 1.0.1走热更更换某个原生插件 → App 版本号从 2.3.0 变到 2.4.0走商店发版两个都在改那就两个版本号都更新习惯是先提交商店版本等上架后再推热更避免用户先收到新资源却发现 App 壳没匹配上。更新触发条件也不是“每次启动就强制下载”需要设计升级策略。我习惯在服务端升级配置里放三个字段新版资源版本号、wgt 下载地址、是否强制升级。App 启动后先拿本地版本号去请求升级接口如果线上版本大于本地版本再根据是否强制来决定弹窗还是静默下载。如果用户正在弱网环境我会选择提示“当前网络不稳定是否立即更新”而不是直接开始下载 wgt不然下载失败概率很高。3.4 热更后的回退与整体更新逻辑热更不可能永远一次成功所以必须把“回退”逻辑想好。我的做法是升级包下载完成后先安装到本地如果安装成功新资源版本号写入本地缓存如果安装失败不能让用户陷入一个不可用的状态要保留上一版资源作为回退。具体代码层面的逻辑大致是// 伪代码式逻辑展示升级判断和安装过程 function checkAppUpdate() { const localVersion uni.getStorageSync(res_version) || 1.0.0 const res await requestUpdateConfig() // 请求升级接口 if (res.version localVersion) { return // 已是最新版 } uni.showLoading({ title: 更新资源包中 }) const downloadResult await uni.downloadFile({ url: res.wgtUrl }) const installResult await new Promise((resolve) { plus.runtime.install(downloadResult.tempFilePath, { force: true }, resolve, reject) }) if (installResult) { uni.setStorageSync(res_version, res.version) // 提示用户重启或直接重启 } else { // 保留旧版本资源下次启动再试 } }这里我特别想说一个容易忽略的点热更安装成功后并不代表你当前的页面就立刻变成新版它需要 App 重启才能全部生效。所以 install 成功之后最好给用户一个“重启应用以应用更新”的按钮或者直接调用退出当前应用的接口重新启动。否则用户会以为热更没成功。4. 常见问题与排查技巧实录4.1 推送场景的典型问题与排查推送配置是从“App 完全收不到通知”到“部分手机收不到通知”这个过程中最容易混淆的。我整理了这几类高频问题第一收不到离线通知。这种情况十有八九是厂商通道没生效。先看 UniPush 后台该设备有没有绑定厂商推送 token如果绑定不了去检查在某个安卓大厂平台创建的推送服务是否通过了审核包名是否和 App 一致。第二能收到通知但点击后无法跳转指定页面。问题出在点击事件的处理。透传类消息可以在回调里自行 navigateTo通知类消息要在点击通知的回调里解析 extra 数据再做跳转。如果这部分代码写错用户每次点击通知都会直接进 App 首页。第三通知要么重复要么完全消失。很多手机上UniPush 的长连接消息和厂商通道消息同时到达会造成重复通知。解决方式一般是设置消息唯一 ID在客户端根据唯一 ID 去重。这个功能在很多推送后台默认不会开启需要手动配置。下面这张速查表是我自己核对推送问题时的模板分享出来现象优先检查点常见解决动作所有手机收不到后台配置 appid、厂商密钥重新编译打包某品牌手机收不到该厂商通道审核/白名单补报备或更换推送服务在线收不到长连接是否建立检查网络权限、推送权限离线收不到厂商通道 token 是否绑定确认系统通知权限开启点击不跳转点击回调逻辑透传消息改用业务类型判断重复收到消息去重在 payload 加唯一 ID4.2 热更新场景的典型问题与排查热更新的问题往往集中在这几类最常见的是“更新了资源版本号但客户端不更新”。这种大多是版本号比较或请求失败导致的。比如客户端本地缓存版本号读取错了或者服务端接口被 CDN 缓存服务端返回的还是旧版本号。我遇到过升级配置接口加了缓存头导致客户端半小时内拿到的都是旧配置清掉 CDN 缓存才恢复正常。第二是“wgt 下载成功但安装失败”。这个大概率是 Android 系统对“未知来源”安装的限制或者 wgt 包本身不完整。务必将 wgt 包在本地解压后检查目录是否完整也建议在下载 wgt 时做一次 MD5 校验防止下载到坏包。这个习惯我是在一次正式发布后学到的教训当时资源包上传到服务器被压缩工具改了二进制导致全量用户安装失败从那以后我每次发版都校验 hash。第三是“热更后白屏或部分页面报错”。这个通常是 JS 资源包和原生壳版本不匹配。新版 JS 用了旧版原生壳不支持的 API一旦出现这类问题基本只能重新发布兼容旧壳的资源包或者引导用户走应用商店升级。所以从设计上就应该避免热更包依赖最新原生 API。4.3 我建议的日常维护流程基于这些踩坑经验我现在给自己的项目定了一套“发布检查清单”每次推送和热更新都按它过一遍也算是我后续一直沿用的日常维护流程第一步准备一台测试手机专门用来验证推送和热更。这台手机不要装太多后台应用便于观察厂商通道是否被系统清理。第二步推送发布前先把 App 杀进程验证一遍离线推送确认通知栏有消息后再全量发送。线上推送最好用“定时推送”或“分批推送”避免消息过多导致厂商通道触发限流。第三步热更发布前将 wgt 包上传到测试环境模拟一个新版本资源走一遍“检测更新、下载安装、重启生效”的完整流程确认无误后再切线上升级配置。第四步线上出问题时优先确认服务端配置和版本号是否正常不要先怀疑客户端代码。大部分“没收到更新”的问题排查到最后都指向 CDN 缓存或接口返回了旧版本号。写在最后的实际体会内容说到这基本把推送和热更新的关键链路都拆开了。最后分享一个我自己在项目里试过的小技巧给热更新接口增加一个“签名参数”比如把版本号加上固定密钥做 MD5 后拼到 URL 上服务端校验签名才返回配置。这样能防止某些环境下升级接口被人恶意刷取虽然会加一点开发量但线上跑起来会更稳。另外每次热更新之前我习惯先在真机上完整走一遍老版本到新版本的升级过程确定回退路径可靠后再切全量。这比任何文档都管用。希望这份学习笔记能让你在真正做 Uniapp 跨端 App 推送与热更新时少踩几个坑早点把精力放回业务本身。
阅读完成 · 觉得有帮助？
