新项目应优先使用uniPush 2.0而非自行接入个推SDK，因其已内置个推能力并自动适配华为、小米、OPPO等厂商通道，省去手动集成、证书管理及多端兼容等复杂问题。
直接说结论：现在新项目别自己接个推 SDK，优先用 uniPush 2.0；它已内建个推能力，还自动适配华为/小米/OPPO 等厂商通道，省掉手动集成、证书管理、多端兼容等一堆坑。
uni.getPushClientId() 返回 undefined 或空字符串？先查这三件事
这不是代码写错了，是环境没跑通：
- 必须用「自定义基座」真机调试——默认基座不带任何厂商 SDK，
uni.getPushClientId()调用直接失败或返回空 - Android 端 manifest.json 里各厂商配置（
huawei、xiaomi、oppo）必须和对应平台控制台信息**逐字匹配**，大小写、下划线、长度全对才行；iOS 则必须上传有效的 APNs 开发/生产证书（P12 或 p8），否则初始化就卡住 - 云服务空间未开通
uniPush 2.0服务：即使客户端全对，cid也只会是undefined，控制台报错"push service not enabled"
manifest.json 的 push 配置怎么填才不白配
填错一个字段，通知栏就收不到。关键字段不是越多越好，而是这几个必须精准：
-
"huawei": { "appid": "xxx" }——这个appid必须和 AGC 控制台「项目设置 → 应用信息」里的完全一致，漏一个字符都不行 -
"xiaomi": { "appid": "xxx", "appkey": "xxx" }——小米的appkey不是首页看到的那个，得去「推送服务 → 应用配置」里单独找 -
"oppo"和"vivo"下的appKey/appSecret别塞错位置；它们还要求手动在系统设置里打开「通知权限」和「自启动权限」，否则通道压根不走 - Android 12+ 必须显式声明
<uses-permission android:name="android.permission.POST_NOTIFICATIONS"></uses-permission>，否则连权限弹窗都不出来
服务端推送只能走 uniCloud 云函数，且不能绕开 getPushManager
uniPush 2.0 的服务端接口是封闭的，硬接个推 REST API 或 APNs 会 401 或静默失败：
- 新建云函数（比如叫
push-message），依赖中只勾选uni-cloud-push扩展库 - 云函数里调用
uniCloud.getPushManager({ appId: "your-appid" })，这个appId必须和开发者中心「uni-push 2.0 → 应用信息」里显示的一致，不是 manifest 里的 bundleId - 推送目标优先用
push_clientid（即cid），别用alias或tag：alias在多设备登录场景下极易冲突，tag同步延迟高，cid是设备唯一且实时可查的“收件地址”
离线消息收不到？重点盯厂商通道是否真生效
iOS 收不到，大概率是 APNs 证书没传对或环境（开发/生产）混了；Android 后台被杀后收不到，90% 是厂商通道没真正打通：
- 华为/小米/OPPO 等厂商通道要求应用**上架其应用商店或通过白名单审核**，否则即使配置全对，离线到达率也极低——这时实际走的是个推自有通道，而该通道在 App 被彻底杀死后无法保活
- 测试时务必用「自定义基座 + 真机 + 应用完全退出」组合验证，模拟器和调试基座无法测离线行为
- 厂商通道是否启用，可在个推控制台或 DCloud 推送日志里看「通道类型」字段，如果是
getui而非huawei/xiaomi，说明厂商通道没走通
