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（设备标识）

javascript 复制代码

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

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

javascript 复制代码

// 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 厂商（华为/小米/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 限制：在线只能收透传，通知仅离线显示
- 解决：透传里自定义内容，前端弹框模拟通知

八、与直接集成个推原生 SDK 的区别

✅ uni-push 2.0 ：DCloud 封装，一行代码接入，自动适配厂商通道，维护成本低
❌ 原生集成个推 SDK：需写 Android/iOS 原生代码，手动适配厂商，复杂且易出错

结论：uni-app 接入个推，首选 uni-push 2.0，按上述步骤配置即可快速实现在线+离线推送。

要不要我给你一份可直接复制的App.vue完整代码（含CID获取、消息监听、点击通知跳转）？