本地通知与系统推送完全不同:前者由App自主定时触发,无需厂商通道;后者需服务端下发且离线可达。uni.showLocalNotification是最轻量实现方式,但需注意权限、渠道、系统版本等兼容要求。

本地通知和系统推送根本不是一回事
很多人以为“本地通知”就是“系统推送”,其实完全两码事。本地通知是 App 自己在前台或后台用 JS 定时触发的,不依赖厂商通道,也不需要 CID、不走个推或华为服务;而系统推送(比如 uniPush)是服务端发、设备离线也能收到,必须配置厂商、打包、获取 cid。如果你只是想在用户打开 App 后,定时弹个“您有新消息”或“打卡提醒”,压根不用搞 uniPush 那套。
uni.showLocalNotification 是最轻量的实现方式
这是 uni-app 原生支持的本地通知 API,不需要任何模块配置、不用改 manifest.json,也不依赖厂商 SDK。但它只在 App 进程存活时有效(即前台或后台未被系统彻底杀掉),且 iOS 上仅支持 iOS 10+,Android 需要 targetSdkVersion ≥ 26 才能显示通知渠道。
- 调用前先检查权限:
uni.getSetting→ 看notification是否已授权,没授权就uni.openSetting引导开启 - 必须指定
channelId(Android)和sound(iOS),否则 iOS 不响、Android 可能静默 - 时间戳要用毫秒,别传错成秒:
date: new Date().getTime() + 60 * 1000 - 示例代码(加了兼容判断):
uni.showLocalNotification({
title: '日程提醒',
body: '下午3点开会',
date: Date.now() + 5 * 60 * 1000,
channelId: 'default',
sound: 'default'
})
为什么 plus.push 不能当本地通知用
很多人看到 plus.push.createMessage 就以为能发本地通知,其实它只是创建一条“内存中的消息对象”,不触发系统通知栏,也不会震动/响铃。它本质是给 receive 事件准备的数据载体,必须配合 plus.push.send(需服务端)或透传逻辑才能落地。误用会导致:控制台没报错,但手机屏幕毫无反应,调试半天才发现根本没走通知系统。
-
plus.push.createMessage≠ 系统通知,它连 Android 的 NotificationCompat.Builder 都没调用 - 真要用 H5+ 做本地通知,得走
plus.notification.create(注意是 notification,不是 push) - 该 API 在 iOS 上受限严重:App 进入后台后,
create调用会失败,返回err: "Not supported" - Android 上也要求 targetSdkVersion ≥ 26,并提前用
plus.notification.setChannel创建渠道
上线前最容易漏掉的两个兼容点
本地通知看着简单,但上线一测就失效,往往卡在这两个地方:一个是 Android 通知渠道没声明,另一个是 iOS 的 Background Modes 没开。它们都不报错,但通知就是不显示、不响铃、不震动。
- Android:在
manifest.json的 “Android 设置” → “应用权限” 里,确保勾选了android.permission.POST_NOTIFICATIONS(Android 13+ 必须);同时在 “Android 模块配置” 中启用Notification(通知)模块 - iOS:必须在 Xcode 工程中手动开启
Background Modes,并勾选Remote notifications—— 即使你不用远程推送,本地通知的定时唤醒也依赖这个开关 - 测试时别只看模拟器:iOS 模拟器不支持通知,Android 模拟器对
POST_NOTIFICATIONS权限响应不稳定,务必真机验证
系统通知栏的“静默”不是 bug,是平台规则写死的。你写的每行通知代码,都得先过厂商那道关,再过系统那道关,最后才到用户眼前。











