更新记录

0.0.2（2026-02-02） 下载此版本

• bugfix

0.0.1（2026-02-02） 下载此版本

-首次发布，支持iOS、Android、HarmonyOS三端的阿里云推送UTS插件

平台兼容性

uni-app x(4.0)

阿里云移动推送 UniApp X 插件

阿里云移动推送（Alibaba Cloud Mobile Push）UniApp X 原生插件，提供 Android、iOS、HarmonyOS 三端统一的推送接口，支持厂商通道，提升消息到达率。

目录

• 版本信息
• 环境要求
• 平台支持
• 快速开始
  • 安装插件
  • 基础配置
  • 初始化
• API 参考
• 类型定义
• 厂商通道配置
• 平台差异说明
• 常见问题
• 更多资源

版本信息

环境要求

Android

• 最低 API Level: 21 (Android 5.0)
• 编译 SDK: 33+
• Gradle: 7.0+
• Kotlin: 1.8+

iOS

• 最低版本: iOS 12.0
• Xcode: 14.0+
• Swift: 5.0+ (暂不支持Swift6)

HarmonyOS

• 最低 API Level: 12
• DevEco Studio: 4.0+
• ArkTS SDK: API 12+

平台支持

快速开始

安装插件

1. 访问 DCloud 插件市场，搜索"阿里云移动推送"
2. 点击"导入插件"将插件添加到项目
3. 在 HBuilderX 中使用云打包获取自定义基座 APP 用于调试

重要提示：UTS 原生插件需要编译为原生代码，标准基座不包含本插件。因此：

• 开发调试阶段：必须使用 HBuilderX 的云打包功能制作包含本插件的自定义基座 APP
• 正式发布阶段：使用云打包或本地打包生成正式包
• 详见 UniApp X 自定义基座使用说明

基础配置

1. 获取推送凭证

前往 阿里云移动推送控制台 创建应用，获取：

• AppKey: 应用唯一标识
• AppSecret: 应用密钥

2. 配置权限（Android）

插件已内置必要权限，无需手动配置。如需自定义，可在 AndroidManifest.xml 中调整：

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />

3. 配置能力（iOS）

在 Xcode 项目中启用 Push Notifications 能力：

1. 打开项目 → Targets → Signing & Capabilities
2. 点击 "+ Capability" → 添加 "Push Notifications"

初始化

在 App.uvue 的 onLaunch 生命周期中初始化：

import * as AliyunPush from '@/uni_modules/alicloud-push'

export default {
  onLaunch() {
    // 1. 设置回调（必须在 start 之前调用）
    AliyunPush.setCallbacks(
      (msg) => {
        // 透传消息回调
        console.log('收到透传消息:', msg.content)
      },
      (notification) => {
        // 通知消息回调（仅前台）
        console.log('收到通知:', notification.title)
      },
      (click) => {
        // 通知点击回调
        console.log('通知被点击:', click.title)
        // 根据 openType 处理跳转逻辑
        if (click.openType === 1 && click.openUrl) {
          uni.navigateTo({ url: click.openUrl })
        }
      },
      (msgId) => {
        // 通知移除回调
        console.log('通知已移除:', msgId)
      }
    )

    // 2. 初始化推送服务
    AliyunPush.start(
      'your_app_key',
      'your_app_secret',
      (res) => {
        console.log('推送初始化成功')
        console.log('设备ID:', res.deviceId)

        // 检查通知权限
        if (!AliyunPush.isNotificationEnabled()) {
          uni.showModal({
            title: '通知权限',
            content: '需要开启通知权限以接收推送消息',
            confirmText: '去设置',
            success: (modalRes) => {
              if (modalRes.confirm) {
                AliyunPush.goNotificationSettings()
              }
            }
          })
        }

        // 3. Android 配置通知通道（Android 8.0+ 必需）
        // #ifdef APP-ANDROID
        AliyunPush.createChannel(
          'default_channel',      // 通道ID
          '默认通知',              // 通道名称
          '接收推送消息',          // 通道描述
          3,                      // 重要性：3-有声音
          undefined,              // allowBubbles
          true,                   // 启用LED灯
          '#0000FF',              // LED颜色
          true,                   // 显示角标
          undefined,              // soundPath
          undefined,              // soundUsage
          undefined,              // soundContentType
          undefined,              // soundFlag
          true,                   // 启用震动
          [0, 300, 200, 300],     // 震动模式
          () => console.log('通知通道创建成功'),
          (err) => console.error('通知通道创建失败:', err.errMsg)
        )
        // #endif

        // 4. 初始化厂商通道（提升消息到达率）
        // #ifdef APP-ANDROID
        // 小米推送（代码配置）
        AliyunPush.initVendorChannel('xiaomi', {
          appId: 'your_xiaomi_app_id',
          appKey: 'your_xiaomi_app_key'
        })

        // 华为推送（需在 build.gradle 配置 manifestPlaceholders）
        AliyunPush.initVendorChannel('huawei', {})

        // 荣耀推送（需在 build.gradle 配置 manifestPlaceholders）
        AliyunPush.initVendorChannel('honor', {})

        // OPPO推送（代码配置）
        AliyunPush.initVendorChannel('oppo', {
          appKey: 'your_oppo_app_key',
          appSecret: 'your_oppo_app_secret'
        })

        // VIVO推送（需在 build.gradle 配置 manifestPlaceholders）
        AliyunPush.initVendorChannel('vivo', {})

        // 魅族推送（代码配置）
        AliyunPush.initVendorChannel('meizu', {
          appId: 'your_meizu_app_id',
          appKey: 'your_meizu_app_key'
        })
        // #endif
      },
      (err) => {
        console.error('推送初始化失败:', err.errMsg)
      }
    )
  }
}

初始化说明：

• 步骤 1-2：所有平台必需，设置回调和初始化推送服务
• 步骤 3：Android 8.0+ 必需，创建通知通道以显示通知
• 步骤 4：Android 可选但强烈推荐，初始化厂商通道提升消息到达率
  • 小米/OPPO/魅族：通过代码传入参数即可
  • 华为/荣耀/VIVO：需先在 build.gradle 配置 manifestPlaceholders（详见 厂商通道配置）
  • 根据实际需要选择初始化的厂商通道，不需要全部初始化
• iOS/HarmonyOS：无需配置通道和厂商推送，系统自动处理

API 参考

核心接口

start(appKey, appSecret, success?, fail?)

初始化推送服务。

参数：

示例：

AliyunPush.start(
  'your_app_key',
  'your_app_secret',
  (res) => {
    console.log('设备ID:', res.deviceId)
  },
  (err) => {
    console.error('错误码:', err.errCode, '错误信息:', err.errMsg)
  }
)

getDeviceId(): string

获取设备唯一标识，用于单设备推送。

返回值： 设备 ID 字符串

注意： 必须在 start 成功后调用。

示例：

const deviceId = AliyunPush.getDeviceId()
console.log('当前设备ID:', deviceId)

setCallbacks(onMessage?, onNotification?, onNotificationClick?, onNotificationRemove?)

设置推送回调函数。

参数：

注意：

• 必须在 start 之前调用，以确保冷启动时的通知点击事件能被正确处理
• 插件已内置冷启动缓存机制

示例：

AliyunPush.setCallbacks(
  // 透传消息
  (message) => {
    console.log('透传消息ID:', message.messageId)
    console.log('消息内容:', message.content)
    console.log('额外数据:', message.extra)
  },
  // 通知消息（前台）
  (notification) => {
    uni.showToast({ title: notification.title || '新消息' })
  },
  // 通知点击
  (result) => {
    console.log('点击类型:', result.openType)
    // openType: 0-默认 1-跳转页面 2-跳转URL 3-打开Activity
    if (result.openType === 1 && result.openUrl) {
      uni.navigateTo({ url: result.openUrl })
    }
  },
  // 通知移除
  (msgId) => {
    console.log('通知已被清除:', msgId)
  }
)

账号管理

bindAccount(account, success?, fail?)

绑定用户账号，支持按账号推送。

参数：

示例：

// 用户登录后绑定账号
AliyunPush.bindAccount(
  'user_12345',
  () => console.log('账号绑定成功'),
  (err) => console.error('账号绑定失败:', err.errMsg)
)

unbindAccount(success?, fail?)

解绑当前设备的账号。

示例：

// 用户退出登录时解绑
AliyunPush.unbindAccount(
  () => console.log('账号解绑成功'),
  (err) => console.error('账号解绑失败:', err.errMsg)
)

listAccount(success?, fail?)

查询当前设备绑定的账号。

注意： HarmonyOS 暂不支持此接口。

示例：

AliyunPush.listAccount(
  (res) => {
    console.log('当前绑定账号:', res.account)
  },
  (err) => console.error(err)
)

别名管理

addAlias(alias, success?, fail?)

为设备添加别名，单设备最多支持 128 个别名。

参数：

示例：

AliyunPush.addAlias('vip_user', () => {}, (err) => {})

removeAlias(alias, success?, fail?)

移除指定别名。

示例：

AliyunPush.removeAlias('vip_user', () => {}, (err) => {})

listAliases(success?, fail?)

查询当前设备的所有别名。

示例：

AliyunPush.listAliases(
  (res) => {
    console.log('别名列表:', res.aliases)
  },
  (err) => console.error(err)
)

标签管理

bindTag(tags, target, alias?, success?, fail?)

绑定标签到设备、账号或别名。

参数：

示例：

// 绑定标签到设备
AliyunPush.bindTag(
  ['vip', 'beijing', 'male'],
  1,
  undefined,
  () => console.log('标签绑定成功'),
  (err) => console.error(err)
)

// 绑定标签到别名
AliyunPush.bindTag(
  ['premium'],
  3,
  'user_alias',
  () => {},
  (err) => {}
)

unbindTag(tags, target, alias?, success?, fail?)

解绑标签，参数同 bindTag。

listTags(target, alias?, success?, fail?)

查询标签列表。

示例：

// 查询设备标签
AliyunPush.listTags(
  1,
  undefined,
  (res) => {
    console.log('设备标签:', res.tags)
  },
  (err) => console.error(err)
)

// 查询别名标签
AliyunPush.listTags(
  3,
  'user_alias',
  (res) => {
    console.log('别名标签:', res.tags)
  },
  (err) => console.error(err)
)

角标管理

setBadgeNum(badgeNum, success?, fail?)

设置应用图标角标数字。

参数：

平台支持： iOS、部分 Android 厂商

示例：

// 设置角标为 5
AliyunPush.setBadgeNum(5, () => {}, (err) => {})

// 清除角标
AliyunPush.setBadgeNum(0, () => {}, (err) => {})

syncBadgeNum(badgeNum, success?, fail?)

同步角标数到阿里云服务器（iOS 专用）。

说明： iOS 需调用此接口将本地角标数同步到服务器，以便服务端推送时使用正确的角标数。

示例：

AliyunPush.syncBadgeNum(3, () => {}, (err) => {})

通知权限

isNotificationEnabled(channelId?): boolean

检查通知权限是否已开启。

参数：

返回值： true-已开启 / false-未开启

示例：

const enabled = AliyunPush.isNotificationEnabled()
if (!enabled) {
  console.log('通知权限未开启')
}

goNotificationSettings(channelId?)

跳转到系统通知设置页面。

参数：

示例：

if (!AliyunPush.isNotificationEnabled()) {
  AliyunPush.goNotificationSettings()
}

Android 专用接口

createChannel(id, name, desc, importance, ...)

创建通知通道（Android 8.0+ 必需）。

参数：

重要性级别：

示例：

// 创建高优先级通道
AliyunPush.createChannel(
  'high_priority',           // 通道ID
  '重要通知',                 // 通道名称
  '重要的推送消息',           // 通道描述
  4,                         // 重要性：最高级
  undefined,                 // allowBubbles
  true,                      // 启用LED
  '#FF0000',                 // 红色LED
  true,                      // 显示角标
  undefined,                 // soundPath
  undefined,                 // soundUsage
  undefined,                 // soundContentType
  undefined,                 // soundFlag
  true,                      // 启用震动
  [0, 250, 250, 250],        // 震动模式
  () => console.log('通道创建成功'),
  (err) => console.error('通道创建失败:', err)
)

// 创建静音通道
AliyunPush.createChannel(
  'silent_channel',
  '静默通知',
  '不打扰的推送消息',
  2,  // 无声音，仅在状态栏显示
  undefined, false, undefined, true,
  undefined, undefined, undefined, undefined,
  false, undefined,
  () => {},
  (err) => {}
)

iOS 专用接口

showNoticeWhenForeground(mode)

设置应用在前台时收到通知的处理模式。

参数：

模式枚举：

import { ForegroundNoticeMode } from '@/uni_modules/alicloud-push'

enum ForegroundNoticeMode {
  CALLBACK_ONLY = 0,       // 仅触发回调，不展示通知
  SHOW_ONLY = 1,           // 仅展示通知，不触发回调
  SHOW_AND_CALLBACK = 2    // 展示通知且触发回调
}

模式对照表：

示例：

import * as AliyunPush from '@/uni_modules/alicloud-push'
import { ForegroundNoticeMode } from '@/uni_modules/alicloud-push'

// 前台时展示通知并触发回调
AliyunPush.showNoticeWhenForeground(ForegroundNoticeMode.SHOW_AND_CALLBACK)

// 前台时仅回调，不展示（默认行为）
AliyunPush.showNoticeWhenForeground(ForegroundNoticeMode.CALLBACK_ONLY)

厂商通道接口

initVendorChannel(channelType, options?)

初始化厂商推送通道，提升消息到达率和实时性。

参数：

厂商配置方式：

详细配置方法请参考 厂商通道配置 章节。

类型定义

PushInitResult

type PushInitResult = {
  deviceId: string    // 设备唯一标识
  success: boolean    // 初始化是否成功
}

PushMessage

interface PushMessage {
  messageId: string           // 消息ID
  title?: string              // 通知标题
  content: string             // 消息内容
  extra?: UTSJSONObject       // 额外数据（JSON 对象）
  messageType: 'notification' | 'message'  // 消息类型
  channel: 'aliyun' | 'vendor'            // 推送通道
}

extra 使用示例：

AliyunPush.setCallbacks((message) => {
  if (message.extra) {
    const orderId = message.extra.get('orderId') as string
    const status = message.extra.get('status') as number
    console.log('订单ID:', orderId, '状态:', status)
  }
})

NotificationClickResult

interface NotificationClickResult {
  messageId: string       // 消息ID
  title?: string          // 通知标题
  content: string         // 通知内容
  extra?: UTSJSONObject   // 额外数据
  openType: number        // 打开方式：0-默认 1-页面 2-URL 3-Activity
  openUrl?: string        // 打开的URL或页面路径
  openActivity?: string   // 打开的Activity类名（Android）
}

openType 说明：

ListTagsResult

type ListTagsResult = {
  tags: string[]          // 标签数组
  target: 1 | 2 | 3       // 目标类型
  alias?: string          // 别名（target=3 时有值）
  success: boolean        // 操作是否成功
}

ListAliasResult

type ListAliasResult = {
  aliases: string[]       // 别名数组
  success: boolean        // 操作是否成功
}

ListAccountResult

type ListAccountResult = {
  account: string | null  // 绑定的账号（未绑定则为 null）
  success: boolean        // 操作是否成功
}

厂商通道配置

厂商通道可显著提升消息到达率，特别是在应用被杀死或后台受限的情况下。

Android 厂商通道

代码配置方式（小米 / OPPO / 魅族 / FCM）

这些厂商支持通过代码传入参数，无需修改 Manifest 文件。

小米推送：

AliyunPush.initVendorChannel('xiaomi', {
  appId: 'your_xiaomi_app_id',
  appKey: 'your_xiaomi_app_key'
})

OPPO 推送：

AliyunPush.initVendorChannel('oppo', {
  appKey: 'your_oppo_app_key',
  appSecret: 'your_oppo_app_secret'
})

魅族推送：

AliyunPush.initVendorChannel('meizu', {
  appId: 'your_meizu_app_id',
  appKey: 'your_meizu_app_key'
})

FCM（Google Firebase）：

AliyunPush.initVendorChannel('fcm', {
  senderId: 'your_fcm_sender_id',
  applicationId: 'your_fcm_application_id',
  projectId: 'your_fcm_project_id',
  apiKey: 'your_fcm_api_key'
})

Manifest 配置方式（华为 / 荣耀 / VIVO）

这些厂商需要在 build.gradle 中配置 manifestPlaceholders，然后调用注册接口。

第一步：配置 build.gradle

在应用的 android/app/build.gradle 中添加：

android {
    defaultConfig {
        // ... 其他配置 ...

        manifestPlaceholders = [
            // 华为推送（注意：需要添加 "appid=" 前缀）
            "hms_appid": "appid=123456789",

            // 荣耀推送
            "honor_appid": "your_honor_app_id",

            // VIVO 推送
            "vivo_appid": "your_vivo_app_id",
            "vivo_appkey": "your_vivo_app_key"
        ]
    }
}

第二步：调用注册接口

// 华为推送（参数已在 Manifest 中配置）
AliyunPush.initVendorChannel('huawei', {})

// 荣耀推送（参数已在 Manifest 中配置）
AliyunPush.initVendorChannel('honor', {})

// VIVO 推送（参数已在 Manifest 中配置）
AliyunPush.initVendorChannel('vivo', {})

注意：

• 如果不使用某个厂商通道，可以设置空字符串，如 "hms_appid": ""
• 华为推送的 hms_appid 必须添加 appid= 前缀，这是华为 SDK 的要求

iOS APNs

iOS 使用系统原生 APNs，插件已自动集成，无需手动配置。

必要配置：

1. 在 Apple Developer 中心创建推送证书
2. 上传推送证书到阿里云控制台
3. 在 Xcode 项目中启用 Push Notifications 能力

HarmonyOS 推送

HarmonyOS 使用华为推送服务，插件在初始化时自动注册，无需手动调用。

必要配置：

在 entry/src/main/module.json5 中添加元数据：

{
  "module": {
    "metadata": [
      {
        "name": "client_id",
        "value": "${clientId}"
      }
    ]
  }
}

平台差异说明

常见问题

1. 初始化失败怎么办？

排查步骤：

1. 检查 AppKey 和 AppSecret 是否正确
2. 确认网络连接正常
3. 查看控制台日志，获取具体错误码
4. Android 需确认已授予必要权限

2. 收不到推送消息？

排查步骤：

1. 检查通知权限是否开启：AliyunPush.isNotificationEnabled()
2. 确认设备已成功注册：检查 getDeviceId() 是否有值
3. 在阿里云控制台查看推送记录和到达率
4. Android 检查是否配置了厂商通道
5. 检查推送目标是否正确（设备ID/账号/标签）

3. 通知点击事件没有触发？

原因： setCallbacks 调用晚于应用启动。

解决方案： 确保在 App.uvue 的 onLaunch 中先调用 setCallbacks，再调用 start。

4. Android 通知没有声音？

原因： Android 8.0+ 需要创建通知通道并设置重要性。

解决方案：

AliyunPush.createChannel(
  'default_channel',
  '默认通知',
  '默认推送消息',
  3,  // 重要性 3 或 4 有声音
  // ... 其他参数
)

5. iOS 前台收不到通知？

原因： iOS 默认在前台时不展示通知。

解决方案：

import { ForegroundNoticeMode } from '@/uni_modules/alicloud-push'
AliyunPush.showNoticeWhenForeground(ForegroundNoticeMode.SHOW_AND_CALLBACK)

6. 厂商通道没有生效？

排查步骤：

1. 确认已正确配置厂商参数（代码或 Manifest）
2. 检查控制台日志，查看厂商 Token 是否成功获取
3. 在阿里云控制台查看设备信息，确认厂商通道是否在线
4. 华为推送需确保 hms_appid 包含 appid= 前缀

7. HarmonyOS 获取不到厂商 Token？

原因： 缺少 module.json5 配置。

解决方案： 在 entry/src/main/module.json5 中添加：

{
  "module": {
    "metadata": [
      {"name": "client_id", "value": "${clientId}"}
    ]
  }
}

8. extra 参数获取不到？

原因： UTS 中 UTSJSONObject 需要使用 .get() 方法访问。

正确用法：

AliyunPush.setCallbacks((message) => {
  if (message.extra) {
    const value = message.extra.get('key') as string
    console.log(value)
  }
})

错误码参考

更多资源

• 阿里云推送控制台: https://emas.console.aliyun.com/
• 官方文档: https://help.aliyun.com/zh/document_detail/434639.html
• UniApp X 文档: https://uniapp.dcloud.net.cn/

技术支持

如遇到问题或有建议，欢迎通过以下方式联系：

• 提交 Issue
• 阿里云工单系统
• 阿里云推送技术支持

最后更新: 2026-01-30