UniApp 快速集成个推推送（UniPush2.0）完整实战教程-平芜编程栈

uni-app 接入个推，官方推荐用uni-push 2.0（底层由个推提供），不用自己集成原生 SDK，全程在 HBuilderX + DCloud 开发者中心配置即可。下面按“开通→配置→客户端→测试→常见坑”一步步来。

一、基本概念

个推（Getui）：第三方推送服务商，提供在线/离线推送。
uni-push 2.0：DCloud 与个推合作的统一推送服务，内置个推+厂商通道（华为/小米/OPPO/VIVO/iOS）。
CID（ClientId）：设备唯一推送标识，用于发消息给指定用户。
在线推送：App 前台运行，走个推长连接。
离线推送：App 后台/被杀，走厂商通道（必须配置厂商证书）。

二、开通 uni-push 2.0（必须）

登录DCloud 开发者中心（https://dev.dcloud.net.cn）
创建应用，填写包名（Android）/Bundle ID（iOS）
左侧菜单 →uni-push→ 选择2.0→立即开通
开通后会拿到：
- AppID（DCloud 应用ID）
- AppKey/AppSecret（uni-push 后台生成）
- 个推后台自动创建应用，无需单独去个推官网创建

三、客户端配置（HBuilderX）

1. manifest.json 开启 uni-push

打开 manifest.json →App模块配置→ 勾选uni-push 2.0
保存后，必须重新编译（或自定义基座）

2. 配置包名/证书（关键）

Android：
- 包名：io.dcloud.xxxx（与开发者中心一致）
- 云打包：发行 → 原生APP-云打包 → 填写包名、签名证书
iOS：
- Bundle ID：与开发者中心、苹果证书一致
- 开启推送能力：Xcode → Signing & Capabilities → 添加Push Notifications

3. 制作自定义调试基座（必做）

标准基座不含推送模块，直接运行会报错：

发行 → 原生APP-云打包 → 勾选制作自定义调试基座→ 打包
打包成功后，运行 → 运行到手机 → 勾选使用自定义基座→ 运行

四、前端代码（获取CID+监听消息）

1. 获取 CID（设备标识）

// 在 App.vue 的 onShow 或首页 onReady 调用uni.getPushClientId({success:(res)=>{constcid=res.clientId;console.log('推送CID：',cid);// 把 cid 传给后端，用于定向推送},fail:(err)=>{console.error('获取CID失败：',err);}});

2. 监听推送消息（在线+离线）

// App.vue 全局监听uni.onPushMessage((res)=>{console.log('收到推送：',res);const{type,data}=res;// type: "notify"（通知）/ "transmit"（透传）// data: 推送内容（title、content、payload 等）// 示例：收到通知后弹框if(type==='notify'){uni.showModal({title:data.title,content:data.content,showCancel:false});}});

五、厂商通道配置（离线推送必备）

Android厂商通道限额
厂商应用开通指南

Android 厂商（华为/小米/OPPO/VIVO）

分别注册对应厂商开发者平台
创建应用，获取AppID/AppKey/AppSecret
在 DCloud 开发者中心 → uni-push →厂商配置填写对应信息

iOS 推送证书

苹果开发者后台 → 生成Push Notification 证书（.p12）
DCloud 开发者中心 → uni-push → iOS 配置 → 上传 .p12 证书 + 密码

六、测试推送

1. 控制台测试（快速验证）

安卓/鸿蒙厂商推送应用创建配置流程
苹果厂商证书配置流程
DCloud 开发者中心 → uni-push →推送测试→ 输入 CID → 发送通知/透传

2. 个推后台查看数据

uni-push 开通后，自动同步到个推后台（https://dev.getui.com），可查看推送记录、设备在线率、到达率

七、常见问题与避坑

收不到推送（在线）
- 未用自定义基座运行
- manifest 未勾选 uni-push 2.0
- 网络限制（公司内网/防火墙）
收不到离线推送
- Android：未配置厂商通道（华为/小米等）
- iOS：证书错误、Bundle ID 不匹配、未开启推送能力
- 应用被系统清理（关闭后台运行）
CID 获取失败
- 包名/Bundle ID 与开发者中心不一致
- 未重新编译或未用自定义基座
iOS 在线收不到通知
- iOS 限制：在线只能收透传，通知仅离线显示
- 解决：透传里自定义内容，前端弹框模拟通知