uniapp通知栏推送不显示如何排查？

Question

问题：在使用 UniApp 实现消息推送时，Android 和 iOS 端均未显示通知栏消息，但日志显示推送已送达。可能原因包括：客户端未正确集成推送 SDK（如厂商通道未配置）、应用处于前台导致系统未弹出通知、推送消息格式错误（透传消息未处理）、或权限未开启（如通知权限被禁用）。此外，HBuilderX 项目中 manifest 配置不完整、离线打包未勾选推送模块，也会导致接收失败。如何系统性排查并定位该问题？

Answer 1

UniApp 消息推送无法显示通知栏的系统性排查指南

一、现象分析与初步判断

在使用 UniApp 实现跨平台消息推送时，开发者常遇到“日志显示消息已送达，但 Android 与 iOS 设备均未在通知栏弹出提示”的问题。该现象表面看似接收正常，实则用户无感知，严重影响产品运营效果。

• 确认推送服务端返回状态码为成功（如：200/OK）
• 检查客户端是否收到 onPushMessage 事件回调
• 验证设备是否处于前台运行状态
• 查看控制台是否有透传消息打印但未处理

二、基础配置核查清单

检查项	Android	iOS	备注
manifest.json 中开启推送模块	✔️	✔️	HBuilderX 必须勾选 "Push"
离线打包包含 Push SDK	✔️	✔️	自定义基座需集成
应用权限申请（通知权限）	自动请求	需手动请求	iOS 需调用 plus.push.request()
证书配置（APNs / 小米/华为等）	厂商通道配置	开发/生产证书正确	尤其注意 Bundle ID 一致
uni.modules 配置文件存在 push 模块	✔️	✔️	检查 build.gradle 或 Podfile

三、分平台深度排查路径

1. Android 端重点排查：
   • 是否启用厂商通道（小米、华为、OPPO、vivo）并上传对应密钥
   • 检查 mainfest.json 中 "push" 节点是否配置 unipush 或第三方服务商
   • 确认应用在后台时能否收到通知栏消息
   • 使用 adb logcat 抓取日志，搜索 D/HuaWei-Push 或 UniPush
2. iOS 端关键点：
   • APNs 证书是否过期或环境不匹配（Development vs Production）
   • 是否在真机运行且已授权通知权限
   • Xcode 控制台是否输出 Registered for remote notifications
   • 检查 entitlements 文件中 aps-environment 是否正确

四、消息类型与处理逻辑差异

UniApp 推送分为两种模式：

// 示例：监听不同类型的消息
plus.push.addEventListener('receive', function(msg) {
    if (msg.payload) {
        // 透传消息：需自行创建通知栏
        const options = {title: '自定义标题', content: msg.content};
        plus.push.createMessage(msg.payload, options);
    } else {
        // 标准通知消息：系统自动展示
        console.log('系统级通知已展示');
    }
}, false);

常见误区是将透传消息误认为应由系统展示，实际需开发者主动调用 createMessage。

五、典型场景流程图分析

graph TD
            A[推送触发] --> B{消息类型?}
            B -->|通知消息| C[系统自动显示通知栏]
            B -->|透传消息| D[执行 receive 回调]
            D --> E{应用在前台?}
            E -->|是| F[不会自动弹出通知]
            E -->|否| G[可配置默认行为]
            F --> H[需手动调用 plus.push.createMessage]
            C --> I[用户可见通知]
            H --> I

六、高级调试手段与工具推荐

• 使用 HBuilderX 自带的“云推送测试”功能发送测试消息
• 通过 adb shell dumpsys notification 查看 Android 通知队列
• iOS 使用 Console.app 过滤 bundle ID 观察 APNs 日志
• 服务端对比 device token 是否有效注册至推送平台
• 启用 unipush 调试模式：plus.push.setDebug(true)
• 检查 uni-push 后台设备在线状态与绑定关系
• 验证 payload 结构是否符合各平台规范（如 iOS 的 alert 字段）
• 测试不同网络环境（WiFi/4G）下的到达率
• 模拟冷启动、热启动、锁屏等多种状态
• 使用 Fiddler/Charles 抓包分析注册与心跳请求