uni.setTabBarBadge不能用于消息列表页内部红点，仅适用于pages.json中tabBar.list配置的底部原生tab项；页面内红点需自定义UI实现。
直接说结论：uni.setTabBarBadge 不能用于“消息列表页”本身的红点提示，它只作用于 pages.json 中配置的原生 tabbar 项——也就是底部那几个固定入口。想在消息列表页面内部显示红点（比如某条聊天记录旁），必须用自定义 UI 实现；而底部 tabbar 上的角标，才是 uni.setTabBarBadge 的合法使用场景。
为什么 setTabBarBadge 在消息列表页调用无效
常见错误是把 uni.setTabBarBadge 放在消息列表页（如 pages/message/message.vue）的 onLoad 或 onShow 里直接调用，结果真机上没反应。根本原因不是 API 调错了，而是：该 API 只对「tabbar 配置项」生效，而消息列表页本身如果不是 tabBar.list 里的页面（比如是跳转进来的二级页），index 参数就找不到对应位置。
- 检查
pages.json中tabBar.list数组，确认消息页是否在其中；若不在，uni.setTabBarBadge({ index: X })的X就是非法索引 - 即使消息页在 tabbar 里，也要确保
index值严格对应数组下标（从 0 开始），别数错 - H5 和 App 平台完全不支持
uni.setTabBarBadge，只在微信/支付宝等小程序平台有效——这点常被忽略
text 必须是字符串，数字会静默失败
传 text: 9 或 text: this.unreadCount（number 类型）不会报错，但 iOS 和多数安卓机型直接忽略。这是最隐蔽的坑，调试时看着代码没问题，实际就是不显示。
- 强制转换：始终用
text: String(unreadCount)或text: `${unreadCount}` - 超长截断：官方限制 text 不超过 3 个半角字符，所以
100可以，1000会被截成空或异常；建议逻辑层提前处理：text: unreadCount > 99 ? '99+' : String(unreadCount) - 空字符串陷阱：传
text: ''在 iOS 上可能残留旧 badge，在安卓上表现不一；清空请用uni.removeTabBarBadge
调用时机不对，真机上大概率白忙活
在 onLoad 甚至 created 里调用，基本等于对空气喊话。tabbar 组件还没挂载完成，API 调了也白调。
- 必须放在
onShow生命周期里，且加一层防抖或延迟：setTimeout(() => { uni.setTabBarBadge(...) }, 100) - Vue 3 + Composition API 下，可用
onActivated替代onShow（尤其配合 keep-alive） - 多端登录或消息跨设备同步时，别依赖本地缓存算未读数；应由全局状态（如 Pinia store）统一管理，并在 store 更新后触发角标刷新
- 避免连续快速调用：比如用户猛戳 tabbar 切换，
set和remove间隔低于 50ms，iOS 会出现闪烁或残留
红点和数字角标不是一回事，别混着用
很多开发者以为 uni.showTabBarRedDot 和 uni.setTabBarBadge 是同一套开关的两个档位，其实它们互不感知、各自独立。你设了数字，红点还亮着；你 hide 了红点，数字照样在。
- 业务逻辑要明确：有具体数字就只用
setTabBarBadge；只要视觉提醒不要数字，才用showTabBarRedDot - 清除时务必双保险：
uni.removeTabBarBadge({ index })+uni.hideTabBarRedDot({ index })，否则某些安卓 ROM（如老版 EMUI）会残留红点 - 不要在同一个
index上交叉调用：先showRedDot再setBadge，部分机型会自动隐藏红点；但反过来removeBadge后红点不会自动出现，得手动showTabBarRedDot
最麻烦的永远不是 API 怎么写，而是各平台原生组件对 badge 的私有渲染规则——iOS 的 UITabBarItem 定位偏移、安卓厂商 ROM 对文字支持度不一、微信开发者工具和真机表现差异极大。所有优化都绕不开真机验证，尤其是华为、OPPO、小米这三类机型，连红点圆角和 z-index 都可能不同。
