新项目必须用unipush 2.0：需自定义基座真机调试、厂商平台注册并严格配置manifest.json、开通绑定unicloud云服务空间，三者缺一不可；1.0已停更且不支持小程序/h5/鸿蒙。
直接说结论：现在新项目别碰 UniPush 1.0（个推旧版），uni.getPushClientId() 拿不到 CID 就是环境没配齐，不是代码问题；UniPush 2.0 是唯一推荐路径，但必须走 uniCloud 云函数 + 自定义基座真机调试，否则连初始化都失败。
为什么 uni.getPushClientId() 一直返回 undefined 或空字符串
这不是 API 调用错了，而是三个硬性条件缺一不可：
- 必须使用「自定义基座」真机调试——默认基座不带任何厂商 SDK，
uni.getPushClientId()会静默失败 - Android 端需在华为/小米/OPPO/VIVO 各自平台完成应用注册，并把对应
appid、appkey填进manifest.json的"huawei"、"xiaomi"等字段，大小写、字符数全要严格匹配 - 云服务空间必须已开通 UniPush 2.0 且完成绑定，控制台里“uniPush 2.0 → 应用信息”显示状态为“已启用”，否则客户端会报错
"push service not enabled"
常见错误现象：HBuilderX 里点“运行到手机”选的是“默认基座”，或者云打包后没填对 Android 包名和 SHA1 签名，都会导致 CID 拿不到。
manifest.json 里 push 配置怎么填才生效
填错一个字段，离线推送就失效。关键只看这几处：
-
"huawei": { "appid": "xxx" }——必须和华为 AGC 控制台「项目设置 → 应用信息」里的appId完全一致（注意不是package name） -
"xiaomi": { "appid": "xxx", "appkey": "xxx" }——appkey不是首页看到的那个，得去「推送服务 → 应用配置」页单独找 -
"oppo"和"vivo"下只填appKey和appSecret，别塞进"huawei"字段里 - 必须显式声明权限：
"permissions": ["android.permission.POST_NOTIFICATIONS"]（Android 12+ 强制要求，漏了通知弹窗根本不会出现）
配置完务必重新云打包，改了 manifest.json 不打包 = 白配。
服务端推送只能用 uniCloud 云函数，不能自己调个推 REST API
UniPush 2.0 的服务端接口是封闭的，硬接个推或 APNs 会直接 401 或静默失败：
- 新建云函数（如
push-message），依赖里只勾选uni-cloud-push扩展库 - 云函数内必须调用
uniCloud.getPushManager({ appId: "your-appid" })，这个appId是开发者中心「uniPush 2.0 → 应用信息」里显示的 ID，不是manifest.json里的包名 - 推送目标优先用
cid，别用alias或tag——cid是设备级唯一标识，多设备登录下不会冲突，alias在用户换设备后极易指向错误终端
如果想让 App 前台也弹通知栏（默认只走 socket），推送时加 force_notification: true 参数。
离线推送收不到？先确认厂商通道是否真正打通
在线推送靠 uniCloud 连接，离线推送全靠厂商通道。很多项目卡在这一步：
- 华为：AGC 控制台必须开启「PUSH 服务」，并上传
agconnect-services.json到 HBuilderX 项目根目录（不是static或uni_modules） - 小米：控制台「推送服务 → 应用配置」里要打开「允许离线推送」开关，否则即使配置了
appid/appkey，App 杀后台后也收不到 - OPPO/VIVO：手机系统设置里要手动打开「通知权限」和「自启动权限」，这两个开关关了，系统级通道压根不走
最容易被忽略的点：离线推送测试必须关闭 App 进程（不是切后台），然后用 DCloud 控制台「测试离线消息」功能发，别用云函数临时跑——云函数默认只触发在线通道。
