UniPush消息推送实战：小米手机离线通道的深度避坑指南
第一次在uni-app里集成UniPush时，我以为按照官方文档一步步操作就能轻松搞定。直到凌晨三点盯着纹丝不动的小米手机通知栏，才意识到自己太天真了。这篇文章不会重复那些官方文档里已有的基础步骤，而是聚焦于那些让我掉进坑里又爬出来的实战经验——特别是小米厂商通道那些令人抓狂的细节。
1. 环境配置：那些文档没告诉你的魔鬼细节
1.1 包名一致性检查的隐藏关卡
小米开放平台要求填写的包名必须与uni-app打包时的包名完全一致，这个大家都知道。但实际操作时会遇到两个隐形陷阱：
# 检查当前项目的包名配置（manifest.json） "app-plus": { "distribute": { "android": { "packagename": "com.yourcompany.appname" # 必须与小米后台完全一致 } } }- 字母大小写敏感：我在测试时曾把"com.TestApp"写成"com.testapp"，导致推送完全失效
- 云打包时的覆盖问题：通过HBuilderX可视化界面修改包名后，必须重新生成自定义基座，单纯保存manifest.json文件不会自动触发重建
1.2 小米开发者账号的"证件照噩梦"
申请小米推送服务时，开发者认证环节的证件照审核堪称玄学。经过五次被拒后，我总结出以下要点：
- 手持身份证照片必须露出完整双耳轮廓
- 身份证信息必须与银行卡开户信息完全一致（包括标点符号）
- 办公环境照片需要包含带小米logo的设备（如用小米手机拍摄）
提示：建议在工作日9:00-11:00提交审核，这个时段通过率较高
2. 离线推送的核心配置：透传消息的死亡迷宫
2.1 小米通道参数配置表
| 参数项 | 正确示例值 | 常见错误值 | 错误后果 |
|---|---|---|---|
| AppID | 2882303761518765432 | 2882303761518765432O | 签名验证失败 |
| AppKey | 566187654321 | 566187654321+ | 连接被拒绝 |
| AppSecret | zxR9LmKYT7qP1sW5vN3oX2y | zxR9LmKYT7qP1sW5vN3oX2 | 消息投递超时 |
2.2 透传消息格式的终极验证方案
官方文档提供的透传模板其实暗藏杀机：
// 这个结构在华为手机正常，但小米会静默丢弃 { "title": "订单提醒", "content": "您有新订单待处理", "payload": {"orderId":123} } // 小米通道兼容版（必须包含特定字段） { "notification": { "title": "订单提醒", "body": "您有新订单待处理" }, "data": { "orderId": "123" } }验证技巧：先在小米开发者平台的"推送测试"工具中发送，确认能收到后再集成到uni-app代码中。
3. 手机系统层的权限陷阱
3.1 小米MIUI系统的特殊权限清单
- 后台弹出界面：设置→应用设置→权限管理→后台弹出界面
- 自启动管理：设置→应用设置→授权管理→自启动管理
- 电池优化：设置→省电与电池→应用智能省电→选择"无限制"
- 通知分类：长按通知→更多设置→设为重要通知
注意：MIUI 12.5以上版本新增了"纯净模式"，会默认禁用非商店应用的推送权限
3.2 动态权限请求的最佳实践
在App.vue的onLaunch中加入以下代码段：
// #ifdef APP-PLUS const main = plus.android.runtimeMainActivity() const Permission = plus.android.importClass('android.content.pm.PackageManager') const Build = plus.android.importClass('android.os.Build') // 检查MIUI通知权限 if (Build.MANUFACTURER === 'Xiaomi') { const Intent = plus.android.importClass('android.content.Intent') const Settings = plus.android.importClass('android.provider.Settings') const intent = new Intent(Settings.ACTION_APP_NOTIFICATION_SETTINGS) intent.putExtra(Settings.EXTRA_APP_PACKAGE, plus.android.runtimeMainActivity().getPackageName()) main.startActivity(intent) } // #endif4. 调试技巧：当推送石沉大海时
4.1 日志抓取三板斧
ADB实时监控：
adb logcat | grep -E "MiPush|PushReceiver"客户端CID验证：
plus.push.getClientInfo((info) => { console.log('小米注册ID:', info.regid) // 重点检查这个值 })服务端回执检查： 在UniPush后台的"推送记录"中，点击每条消息查看"设备到达数"
4.2 常见错误代码速查表
| 错误码 | 含义 | 解决方案 |
|---|---|---|
| 20002 | 无效的AppID | 检查小米后台与UniPush配置是否同步 |
| 20007 | 消息体超过4KB | 压缩payload数据 |
| 20016 | 每日推送限额耗尽 | 申请提高配额或优化推送策略 |
| 20035 | 设备未注册到小米通道 | 检查客户端regid获取逻辑 |
5. 性能优化：从能用到好用的进阶之路
5.1 消息合并推送策略
当需要发送多条关联消息时（如聊天应用），可以使用小米的"折叠消息"功能：
const notification = { title: "新消息", body: "您有3条未读消息", extra: { "mipush_notify_style": "1", // 启用折叠 "mipush_group": "chat_msg" // 同一分组会折叠 } }5.2 离线消息存活时间配置
对于时效性强的消息（如验证码），建议设置TTL：
{ "notification": {...}, "android": { "ttl": "60s" // 60秒后未送达则丢弃 } }实际测试发现，小米手机在省电模式下会自动延长TTL约30%，这点需要在实际业务逻辑中考虑进去。
