1. 从零开始：理解UniPush与个推的核心机制

如果你正在用uni-app开发跨端应用，并且想给用户发个消息提醒，比如“您的订单已发货”或者“您有一条新消息”，那你大概率绕不开UniPush。很多新手朋友一上来就被“UniPush”、“个推”、“厂商通道”、“通知消息”、“透传消息”这些词给整懵了，感觉配置起来也是一头雾水，明明后台显示推送成功了，手机就是没反应，或者点了通知没跳转，坑是一个接一个。

别急，我刚开始用的时候也这样，踩过不少坑。今天我就用最直白的话，结合我这几年折腾推送功能的实战经验，帮你把UniPush和个推的调试过程彻底捋清楚。咱们的目标就一个：让你能稳定、精准地把消息推送到用户的手机上，不管是App开着还是关着。

首先，你得明白它们仨是啥关系。你可以把个推想象成一家专业的“快递公司”，它在全国（全球）有非常强大的物流网络（推送链路），专门负责把“包裹”（推送消息）从你的服务器送到用户的手机。而UniPush呢，是DCloud（uni-app的官方）基于个推等服务，为你封装好的一个“快递下单平台”。你不需要直接去跟复杂的快递公司（个推原生SDK）打交道，只需要在uni-app这个熟悉的开发环境里，通过UniPush提供的统一接口，就能轻松下单发快递了。

那为什么需要这个“下单平台”呢？因为安卓手机品牌太多了，华为、小米、OPPO、vivo...每家都有自己的“小区快递柜”（系统级推送通道，也叫厂商通道）。如果你的App被用户杀死了（退到后台），你的“快递员”（App进程）就进不了小区，包裹就送不到用户手上。这时候，个推这家快递公司就会调用对应手机品牌的“快递柜”（厂商通道）来帮你送货，这就是所谓的离线推送。UniPush帮你把这些不同厂商的复杂配置都集成好了，你只需要在后台勾选、配置几个关键参数就行，大大降低了难度。

所以，整个流程简单概括就是：你的服务器 -> 通过UniPush接口 -> 调用个推服务 -> 个推根据手机状态和品牌 -> 选择通过App在线通道或厂商通道 -> 将消息送达用户手机。理解了这个基本模型，后面所有的调试和问题排查就有了方向。

2. 环境搭建与调试基座：你的第一个“调试神器”

理论懂了，咱们就得动手。调试推送功能，第一步不是写代码，而是准备好调试环境。很多朋友直接在HBuilderX里运行到标准基座或真机，然后就发现收不到推送，或者事件不触发，根本原因就是调试环境没配置对。

核心一步：制作自定义调试基座。 这是uni-app调试原生插件功能（Push模块就是原生插件）的必备操作，千万不能省。为什么？因为标准运行基座里没有包含你配置的Push模块和个推SDK，只有自定义调试基座才会把你manifest.json里勾选的所有原生模块都打包进去。

具体操作，我带你走一遍：

1. 打开你的uni-app项目，找到 manifest.json 文件，切换到“App模块配置”选项卡。
2. 在“模块权限配置”里，找到“Push(消息推送)”，务必勾选上。这一步相当于告诉打包工具：“我这个App需要推送功能，请把相关的代码和SDK给我加进去。”
3. 点击HBuilderX顶部菜单的“发行” -> “原生App-本地打包” -> “制作自定义调试基座”。这个过程其实就是用你当前的配置，重新编译一个专门用于调试的App安装包。
4. 等待编译完成。成功后，用数据线连接你的安卓手机，并开启USB调试模式。在HBuilderX的运行菜单里，选择“运行到Android App基座”，然后选择你刚才打好的自定义调试基座。手机会自动安装这个调试版App。

好了，现在你的手机上安装的，就是一个包含了完整UniPush（个推）SDK的App了。这是所有后续调试工作的基础，没有这个，很多推送行为根本无法触发。

调试过程中，有一个非常重要的工具：UniPush后台管理界面。地址是 https://dev.dcloud.net.cn/uni/push。在这里，你可以做两件关键事：

• 查询设备状态：当你的调试App在手机上启动后，它会自动向个推服务器注册，并获得一个唯一的身份标识，叫做 CID。你可以在App启动时打印这个CID（通过 plus.push.getClientInfo() 获取），然后把这个CID填到UniPush后台的“CID查询”框里。你能清晰看到这台设备的在线状态、所属厂商等信息。如果这里查不到，说明SDK集成或初始化有问题。
• 手动推送测试消息：后台提供了手动推送功能，你可以选择“通知消息”或“透传消息”，填写标题和内容，指定推送给刚才查询到的CID，进行实时测试。这比从自己服务器发要快捷直观得多，是前期调试的利器。

3. 通知消息 vs 透传消息：彻底搞懂两者的本质区别

这是UniPush调试中最核心、也最容易踩坑的概念。很多开发者消息发不出去，或者事件不对，根源就是没弄明白它俩的区别。我用一个比喻来说：

• 通知消息：就像你收到一个邮局送来的实体信件。邮递员（系统）会把信（通知）直接投递到你家的邮箱（手机通知栏）。你不需要在家（App打开），邮递员也会塞进去。你看到邮箱上有信，去打开邮箱、取出信件、阅读内容，这个过程就是点击通知栏。信件本身（通知的标题和内容）是邮递员（系统）直接展示给你的。
• 透传消息：则像一封加密电报。电报局（个推）只负责把电报送到你家门口（App进程）。但电报内容是加密的，电报局的人看不懂，也不会帮你念出来。只有你自己（你的App代码）用密码本（你约定的数据格式）解密后，才知道里面写了什么，然后决定要做什么——可能是更新界面上的某个数字，可能是播放一段声音，也可能是在后台静默处理一些数据。

基于这个比喻，它们的核心差异和技术特性对比如下：

特性维度	通知消息	透传消息
展示形式	由手机系统统一展示在通知栏。有图标、标题、内容，用户可见。	系统不直接展示。消息内容对系统透明（故名“透传”），由App自己处理。
触发条件	无论App在前台、后台还是被杀死，只要集成了厂商通道并配置正确，都能收到并展示。	通常需要App进程存活（在前台或后台）。App被杀死后，普通透传消息无法送达（依赖厂商通道的特殊透传除外）。
核心事件	主要触发 click 事件。用户点击通知栏消息时触发。	主要触发 receive 事件。消息到达App时立即触发。
数据承载	主要通过 payload 字段携带自定义数据，用于点击后跳转特定页面。	整个消息体都是自定义的，可以传递复杂的JSON数据供App业务逻辑使用。
用途	用于强提醒，如新闻推送、订单状态变更、社交消息提醒等。	用于静默更新，如数据同步、后台日志上报、实时更新App内未读消息数等。

最关键的坑来了，也是我原文中提到的：通知消息的 receive 事件是不会触发的！ 这是由它们的机制决定的。通知消息的路径是：个推服务器 -> 手机系统通知服务。消息在到达系统通知栏的那一刻，推送链路对个推来说就已经结束了，它不会再去唤醒你的App并触发 receive 事件。只有用户点击了通知栏，系统才会把你的App唤醒或调到前台，并触发 click 事件，这时你才能拿到 payload 数据。

而透传消息的路径是：个推服务器 -> 你的App进程。消息是直接交给你的App代码的，所以消息一到，receive 事件立刻触发，你就可以在里面执行任何逻辑。如果你需要消息一到达就立刻让App有所反应（比如即时通讯聊天，消息一来就要更新界面和播放提示音），那么必须使用透传消息。

4. 消息监听与事件处理：编写健壮的接收代码

理解了消息类型，我们来看看在uni-app里怎么写代码来接收它们。这里有两种写法，一种是使用5+ API（Webview环境），另一种是使用uni.$on（Vue环境），我建议在uni-app项目中主要使用5+ API的方式，因为它更底层、更可靠。

代码要写在哪里？通常是在 App.vue 的 onLaunch 生命周期中。因为推送监听是全局的，需要尽早建立。

// 在 App.vue 的 script 部分
export default {
  onLaunch: function() {
    // 初始化推送监听
    this.initPush()
  },
  methods: {
    initPush() {
      // 判断运行环境，确保在5+环境（即App环境）下执行
      if (typeof plus !== 'undefined') {
        // 监听点击消息事件（主要处理通知消息）
        plus.push.addEventListener('click', (msg) => {
          console.log('【推送点击】', JSON.stringify(msg));
          // 这里的 msg 对象结构很关键：
          // - msg.content: 通知的内容
          // - msg.payload: 服务端发送的自定义数据（JSON字符串）
          // - msg.title: 通知的标题
          
          // 示例：解析payload并跳转
          try {
            const payload = JSON.parse(msg.payload);
            if (payload.type === 'order') {
              // 跳转到订单详情页
              uni.navigateTo({ url: `/pages/order/detail?id=${payload.orderId}` });
            } else if (payload.type === 'news') {
              // 跳转到新闻详情页
              uni.navigateTo({ url: `/pages/news/detail?id=${payload.newsId}` });
            }
          } catch (e) {
            console.error('解析payload失败:', e);
            // 即使解析失败，也可以跳转到默认首页
          }
          // 可以加一个原生提示，用于调试
          // plus.nativeUI.alert(`点击了通知: ${msg.title}`);
        }, false); // 注意这个false参数，代表不捕获事件冒泡

        // 监听在线消息事件（主要处理透传消息）
        plus.push.addEventListener('receive', (msg) => {
          console.log('【推送接收】', JSON.stringify(msg));
          // 注意：只有透传消息才会触发这个事件！
          // 透传消息的整个 msg 内容都是服务端传过来的自定义数据
          
          // 示例：收到透传消息，更新App内部状态或发出全局事件
          try {
            const data = JSON.parse(msg.content); // 透传消息内容在content字段
            if (data.cmd === 'update_badge') {
              // 更新应用角标
              plus.runtime.setBadgeNumber(data.count);
            }
            // 使用uni.$emit通知所有页面
            uni.$emit('newPushMessage', data);
          } catch (e) {
            console.error('处理透传消息失败:', e);
          }
          // 调试提示
          // plus.nativeUI.alert(`收到透传消息: ${msg.content}`);
        }, false);

        console.log('推送事件监听器已注册');
      } else {
        console.warn('当前非5+环境，无法注册推送监听');
      }
    }
  }
}

几个必须注意的坑点：

1. 事件重复注册：addEventListener 可能会被多次调用（比如热重载时），导致同一个事件处理函数被绑定多次，触发多次。可以在注册前先调用 plus.push.removeEventListener 移除旧监听，或者确保初始化代码只执行一次。
2. payload格式：服务端发送的 payload 应该是一个JSON字符串，而不是JSON对象。在客户端需要用 JSON.parse 解析。如果服务端传的是对象，需要先 JSON.stringify。
3. 透传消息的content：对于透传消息，服务端发送的整个消息体，在客户端是通过 msg.content 来获取的，而不是 msg.payload。payload 字段在透传消息里通常是空的。
4. 调试时多用console.log：把 msg 对象整个打印出来，看清它的结构，这是解决“为什么拿不到数据”问题最快的方法。

5. 服务端推送实战：关键参数配置与避坑

客户端准备好了，现在轮到服务端发力了。无论你用Node.js、Java、Python还是PHP，调用个推的API进行推送，有几个参数配置直接决定了消息能否正确送达和触发预期事件。

这里以个推常用的HTTP API为例，讲解关键参数。假设你要推送一条“订单发货”的通知。

场景一：推送一条点击后跳转到订单详情的通知消息

// 这是一个示例的请求体 (JSON)
{
  "request_id": "1234567890", // 请求ID，用于去重和排查
  "audience": {
    "cid": ["用户的CID"] // 这里填写目标设备的CID，可以多个
  },
  "push_message": {
    "notification": {
      "title": "您的订单已发货", // 通知栏标题
      "body": "商品正在飞速奔向您，点击查看物流详情", // 通知栏内容
      "click_type": "payload", // 关键！点击动作类型
      "payload": "{\"type\": \"order\", \"orderId\": \"202310270001\", \"page\": \"/pages/order/logistics\"}" // 自定义数据，必须是字符串
    }
  }
}

• click_type：这里设为 "payload"，表示点击通知后，会将 payload 数据传递给客户端App，触发 click 事件。这是最常用的方式。
• payload：必须是一个JSON字符串。里面包含你约定好的业务数据，客户端解析后就能知道该跳转到哪个页面、带什么参数。

场景二：推送一条静默更新未读消息数的透传消息

{
  "request_id": "1234567891",
  "audience": {
    "cid": ["用户的CID"]
  },
  "push_message": {
    "transmission": "{\"cmd\": \"update_badge\", \"count\": 5}" // 关键！transmission字段，内容完全自定义
  }
}

• 透传消息使用 transmission 字段，其值也是一个字符串（通常也是JSON字符串）。这个消息会原封不动地传给客户端，并触发 receive 事件。
• 透传消息没有标题和内容，不会展示在通知栏，除非你在客户端的 receive 事件监听里，自己调用 plus.push.createMessage 来创建一条本地通知。

服务端配置的大坑：

1. 离线消息失效：如果你希望App被杀死后也能收到通知消息，必须配置并启用厂商通道（小米、华为、OPPO、vivo等）。这需要在UniPush后台和各厂商开发者平台分别配置应用和密钥。否则，App进程一死，通知就收不到了。
2. 透传消息的离线送达：标准透传消息在App被杀死后是无法送达的。个推提供了“纯透传消息离线保存”的功能（需在推送API中设置 settings 下的 ttl 存活时间），但即使保存了，也需要等用户下次启动App时才能收到。如果要求即时性，仍需依赖通知消息或厂商通道的特殊透传。
3. 消息去重：务必使用 request_id。个推服务器在短时间内收到多个相同 request_id 的推送请求，可能会视为重复而忽略。可以用“时间戳+随机数”来生成。

6. 深度调试与疑难杂症排查指南

当推送不成功时，别慌，按照以下步骤层层排查，像侦探一样找到问题根源。

第一步：检查设备CID与在线状态

1. 确保客户端App成功获取到CID，并在控制台打印出来。
2. 将CID复制到UniPush后台 (dev.dcloud.net.cn/uni/push) 查询。如果查询不到，说明个推SDK注册失败。可能原因：项目包名（Bundle Identifier）与DCloud开发者中心申请UniPush时填写的包名不一致；自定义调试基座未正确制作。
3. 查询结果中，看设备是否在线。如果离线，可能是网络问题，或者App被系统强力清理了。

第二步：检查推送记录与回执

1. 在UniPush后台或个推开发者后台，查看推送记录。看消息是否显示“已发送”、“已到达”或“点击”。
2. 如果显示“发送失败”，查看失败原因。常见原因：CID无效、AppKey/AppSecret配置错误、证书问题（iOS）、厂商通道配置错误。
3. 利用个推的“任务详情”功能，查看消息具体的下发路径，是走了在线通道还是厂商通道。

第三步：客户端日志分析

1. 使用 adb logcat 抓取安卓日志。这是高级调试的终极武器。在命令行输入 adb logcat | grep -i "push\|个推\|Gt\|notification"，可以过滤出所有与推送相关的系统及SDK日志。你能看到SDK初始化、注册CID、收到消息、创建通知等全过程。
2. 在客户端事件监听函数里，把整个 msg 对象用 console.log(JSON.stringify(msg)) 打印出来。确认事件是否触发，以及数据格式是否正确。
3. 检查是否被手机系统或安全软件拦截。部分国产手机有“智能通知管理”或“纯净后台”功能，会禁止非白名单App的后台活动，导致透传消息无法触发 receive 事件。需要引导用户手动设置。

第四步：特定场景问题

• 问题：iOS能收到，安卓收不到。
  • 排查：99%是安卓厂商通道未配置或配置错误。逐一检查小米、华为等平台的AppID、AppKey、AppSecret是否在UniPush后台正确填写，证书是否上传。
• 问题：点击通知没反应，不跳转。
  • 排查：首先检查 click 事件是否触发（加alert调试）。如果触发，检查 payload 解析是否出错，或跳转逻辑代码有Bug。如果没触发，检查服务端推送的 click_type 是否设置为 "payload"。
• 问题：App在前台时，通知不显示在通知栏，直接触发事件。
  • 这是正常行为！个推/UniPush的默认策略就是如此。如果希望即使App在前台也显示通知栏，需要在服务端推送时，针对安卓平台设置 notification 下的 channel_id 为一个有效的渠道ID，并且客户端需要创建对应的通知渠道（Android 8.0以上）。或者，在客户端的 receive 事件里，自己调用 plus.push.createMessage 创建一条本地通知。

调试推送是个细致活，很多时候问题出在配置的某个小细节上。我的经验是，养成好习惯：客户端打印CID和完整消息对象；服务端记录每次推送的请求和响应；善用后台的查询工具。把这些信息都串联起来，大部分问题都能迎刃而解。