uni-app app端推送通知收不到,主因是原生通道未打通:ios需apns证书配置,android需厂商通道(华为、小米等)或fcm接入,且manifest.json须勾选push模块、系统通知权限需开启。

uni-app App端推送通知为什么收不到?先看通道是否打通
uni-app 的 App 端消息推送,本质依赖原生通道:iOS 用 APNs,Android 用厂商通道(华为、小米、OPPO、vivo)或 FCM(仅测试/海外包)。uni.push 不是万能中转,它只是封装层,底层必须完成对应平台的配置和证书/密钥接入。常见现象是 HBuilderX 打包后「本地调试能弹窗,上线后静默无通知」——大概率是厂商通道未开通或配置错误,比如华为的 agconnect-services.json 没放对位置,或 OPPO 的 oppo_push_app_key 没填进 manifest.json。
- 检查
manifest.json中「App 模块配置」是否勾选了「Push(消息推送)」 - iOS 需在 Apple Developer 后台开启 Push Notifications Capability,并上传 .p12 推送证书到 DCloud 后台
- Android 各厂商通道需单独申请应用 ID、密钥,在 DCloud 的「开发者中心 → 应用配置 → 推送设置」里逐个填写
- 真机运行时,务必确认手机系统未全局关闭该 App 的通知权限(尤其华为 EMUI 和小米 MIUI)
如何让通知到达时播放提示音?关键在 payload 配置
提示音不是前端代码控制的,而是由推送服务下发的 payload 决定。iOS 要求 sound 字段明确指定音频文件名(如 "default" 或自定义 "alarm.caf"),Android 厂商通道则依赖 sound + channelId 组合生效。DCloud 的 uni.push.send API 不直接暴露 sound 字段,得走「透传消息 + 客户端本地构建通知」这条路才可控。
- 服务端推送时,避免只发
title和content,必须带上sound: "default"(iOS)或android_sound: "default"(Android 厂商通道) - 若使用 DCloud 自建推送后台,进入「推送管理 → 消息模板」,在「高级参数」里手动添加 JSON 字段:
{"sound":"default"} - 更稳妥的做法是服务端发透传消息(
type=3),App 收到后调用uni.showNotification并传入{ sound: true }—— 这样可确保音效触发,但需自行处理点击跳转逻辑
uni.showNotification 能否替代厂商推送?适用场景有限
uni.showNotification 是纯前端 API,只能在 App 前台活跃时触发,且不支持后台唤醒、锁屏显示、角标更新等能力。它适合内部状态提醒(如表单提交成功、下载完成),但不能替代真正的推送服务。
- 前台调用
uni.showNotification时,sound: true参数在 iOS 和部分 Android 厂商系统上有效;但华为、小米等要求必须创建 NotificationChannel 并设置setSound(),否则静音 - Android 8.0+ 必须提前注册 channel,否则通知不显示。可在
onLaunch中调用原生插件或使用uni.getProvider获取 push provider 后初始化 - 不要指望
uni.showNotification在 App 杀进程后还能响铃——它根本不会执行
调试阶段最容易忽略的三个细节
很多问题卡在看似无关的配置项上,而不是代码逻辑本身。
- 打包时「基础库版本」必须 ≥ 3.4.0,旧版
uni.push对 sound 字段支持不完整 - HBuilderX 运行到真机时,勾选「启用调试模式」会导致推送被拦截,正式打包前务必关闭
- vivo 和 OPPO 对通知文案长度敏感,超限会自动丢弃 sound 字段,建议 title ≤ 20 字、content ≤ 50 字
真正难的不是写几行 JS,而是把每个平台的证书、密钥、channel、权限、后台开关全部对齐。漏掉任意一环,提示音就哑火。











