更新记录

1.0.0（2026-06-23） 下载此版本

新增 UniPush 运行环境、cid 和 manifest 摘要诊断。 新增 H5、小程序与 App 推送链路差异提示。 新增可复制的诊断结果格式化方法和示例页面。

平台兼容性

uni-app(3.97)

UniPush 推送配置诊断工具

JQ-UniPushDoctor 用于把 UniPush 常见问题整理成可截图、可复现的诊断结果，适合排查 cid 获取不到、运行平台不对、manifest 配置缺项、H5/小程序与 App 推送链路混淆等问题。

能做什么

• diagnoseUniPush(options)：根据平台、运行环境、provider、cid、manifest 摘要生成诊断报告。
• collectUniPushRuntime(options)：在运行时尽量采集 uniPlatform、App 运行环境和 uni.getPushClientId 结果。
• formatDiagnosis(report)：把诊断报告转成适合复制或截图反馈的文本。

快速使用

const pushDoctor = require('@/uni_modules/JQ-UniPushDoctor/js_sdk/jq-unipush-doctor/index.js')

const report = pushDoctor.diagnoseUniPush({
  platform: 'app',
  runtime: 'app-plus',
  provider: 'unipush2',
  cid: '',
  manifest: {
    appid: '__UNI__XXXX',
    appName: 'Demo',
    unipush: {
      enable: true
    }
  }
})

console.log(report)
console.log(pushDoctor.formatDiagnosis(report))

自动采集运行环境

const pushDoctor = require('@/uni_modules/JQ-UniPushDoctor/js_sdk/jq-unipush-doctor/index.js')

pushDoctor.collectUniPushRuntime({
  provider: 'unipush2'
}).then((runtime) => {
  const report = pushDoctor.diagnoseUniPush({
    ...runtime,
    manifest: {
      appid: '__UNI__XXXX',
      appName: 'Demo',
      unipush: {
        enable: true
      }
    }
  })
  console.log(report)
})

常见判断

• App 端 cid 为空：优先确认 UniPush 是否开通、是否重新制作自定义基座或云打包包体、是否在真机运行。
• H5 / Web：只能做参数检查，不能证明 App UniPush 通道可用。
• 小程序：订阅消息链路和 App UniPush 不是同一套链路，需要分开排查。
• manifest 摘要缺失：只能检查运行环境和 cid，无法判断项目配置是否完整。

隐私和权限

插件不申请 Android/iOS 原生系统权限，不内置广告 SDK，不上传、不存储、不统计终端用户数据。诊断函数只处理调用方传入的本地参数；如果业务项目实际使用推送、通知或厂商通道，请按 UniPush 官方要求在自己的项目中配置。

适合谁

• App 真机运行时拿不到 cid 的项目。
• 不确定 HBuilderX 标准基座、自定义基座、云打包包体差异的项目。
• 需要把推送失败信息整理成截图发给维护者或团队排查的项目。