uni.showlocalnotification实现本地通知需检查三项:权限(uni.getsetting+uni.opensetting)、android channelid(manifest声明)、ios sound及background modes;plus.notification.create为底层替代方案,需手动设渠道与监听点击。

别混淆“本地通知”和“系统推送”——前者是 App 自己定时弹的,后者是服务端发、离线也能收的。你如果只想要“打卡提醒”“会议通知”这类前台/后台存活时触发的提示,uni.showLocalNotification 就够了;真要关机后还能收到消息,必须走 uniPush + 厂商通道。
uni.showLocalNotification 调用前必须检查的三件事
这个 API 看似简单,但漏掉任意一项,iOS 不响、Android 不显示、控制台还完全不报错。
- 权限没开:调用前必须
uni.getSetting检查notification字段是否为true,否则直接静默失败;没授权就立刻uni.openSetting引导用户开启 - Android 渠道缺失:targetSdkVersion ≥ 26 后,
channelId不仅要传,还必须提前在原生层声明(uni-app 默认没做);不声明=通知被系统丢弃 - iOS 静音陷阱:
sound: 'default'必须显式传,且 App 的 Background Modes 要勾选 “Remote notifications”,否则即使前台运行也不播放提示音
示例写法(含兜底):
uni.getSetting({ success: (res) => { if (res.authSetting['scope.notification'] !== true) { uni.openSetting({ success: openRes => { if (openRes.authSetting['scope.notification']) showNoti(); } }); return; } showNoti(); } });
showNoti() 内部必须带 channelId(Android)和 sound(iOS):
uni.showLocalNotification({ title: '打卡提醒', body: '请在10分钟内完成签到', date: Date.now() + 5 * 60 * 1000, channelId: 'work', sound: 'default' });
plus.notification.create 是更底层但更可控的替代方案
当 uni.showLocalNotification 因渠道或后台限制失效时,plus.notification.create 可绕过部分限制,但它不是“开箱即用”——你需要自己处理渠道创建、PendingIntent 构造、点击回调绑定。
- iOS 上它只在 App 前台有效,进入后台后调用直接返回
err: "Not supported" - Android 必须先调用
plus.notification.setChannel创建渠道,否则create会静默失败 - 点击通知后不会自动跳转页面,得手动监听
plus.notification.addEventListener('click', ...)并uni.navigateTo
关键代码片段:
plus.notification.setChannel({ id: 'alarm', name: '闹钟提醒', importance: 4 }); // Android 8.0+ 必须
plus.notification.create(1, '会议开始', '请立即加入', { channel: 'alarm' });
plus.notification.addEventListener('click', (msg) => { uni.navigateTo({ url: '/pages/meeting/index?id=' + msg.payload }); });
为什么 plus.push.createMessage 不是本地通知
很多人看到 plus.push.createMessage 就以为能发通知,结果调试半天手机毫无反应——因为它根本没调用系统通知 API,只是在内存里建了个消息对象。
- 它不触发通知栏、不震动、不响铃,连
plus.push.send都不调用(那是服务端行为) - 它的存在意义是给
plus.push.addEventListener('receive', ...)提供数据载体,属于“推送接收链路”的一环,不是“通知展示链路” - 误用后果:控制台无报错、日志里有 create 成功记录,但用户永远看不到任何提示
真要本地推送,别碰 plus.push,盯死 uni.showLocalNotification 或 plus.notification。
上线前最容易被忽略的两个兼容点
90% 的“测试正常、上线全挂”问题都卡在这儿:
- Android 打包时未在
manifest.json的 “App 模块配置” → “推送模块” 中勾选 “通知栏消息”,导致云打包后channelId全部失效 - iOS 在 Xcode 工程里没打开 “Signing & Capabilities” → “Background Modes” → “Remote notifications”,导致后台状态下
sound参数被忽略
这两个开关不手动点开,哪怕代码写得再对,通知也会变成哑巴。











