保姆级教程：从零配置uni push2.0到云函数发送推送（阿里云版）
保姆级教程：从零配置uni push2.0到云函数发送推送（阿里云版）
第一次接触uni-app和uniCloud的开发者，往往在集成推送功能时遇到各种"坑"：证书配置复杂、厂商通道对接困难、云函数部署失败......本文将用最直观的方式，带你一步步完成uni push2.0的全流程配置，特别针对阿里云环境下的常见问题提供解决方案。无论你是需要实现在线推送还是离线推送，都能在这里找到清晰的指引。
1. 准备工作：开通uniCloud阿里云服务
在开始配置推送功能前，我们需要先确保uniCloud环境已正确搭建。以下是具体操作步骤：
创建uniCloud服务空间
在HBuilderX中右键项目目录，选择"创建uniCloud云开发环境"，服务商选择"阿里云"。如果已有项目未关联uniCloud，可通过右键项目→"关联云服务空间"完成绑定。开通推送服务
进入uniCloud控制台，在"服务空间"中找到你的项目，确保以下服务已开通：- 云函数
- 数据库
- 存储
注意：阿里云版uniCloud需要实名认证后才能使用推送服务，请提前完成企业或个人认证。
常见问题排查：
- 若出现"权限不足"提示，检查账号是否具备SpaceAdmin权限
- 创建服务空间时推荐选择"按量计费"模式，新用户有免费额度
- 地域选择建议：国内用户选"华东2（上海）"，海外用户选"香港"
2. 证书申请：安卓与iOS配置详解
推送功能必须配置平台证书才能正常工作，这是最容易卡住的环节之一。
2.1 安卓证书配置
安卓平台需要准备：
- 应用包名（如com.example.app）
- SHA256指纹证书
- 各厂商推送密钥（华为、小米等）
具体操作流程：
# 生成签名证书命令示例（Java环境需已配置） keytool -genkey -v -keystore my-release-key.jks -keyalg RSA -keysize 2048 -validity 10000 -alias my-alias将生成的.jks文件中的SHA256值填入uniPush控制台的"应用信息"→"安卓平台配置"。
2.2 iOS证书配置
iOS需要准备：
- Bundle ID（必须与APP完全一致）
- APNs推送证书（分开发和生产环境）
关键步骤：
- 登录Apple开发者账号
- 进入Certificates, Identifiers & Profiles
- 创建APNs类型的证书（选择Apple Push Notification service SSL）
- 下载.p12文件并上传到uniPush控制台
重要提示：iOS13+必须配置push entitlements，在Xcode项目的Signing & Capabilities中添加Push Notifications能力。
3. 厂商通道配置与问题排查
为实现离线推送，必须配置各手机厂商的推送通道。以下是主流平台的配置要点：
| 厂商 | 申请地址 | 必填字段 | 常见错误 |
|---|---|---|---|
| 华为 | 开发者联盟 | App ID, App Secret | 签名证书不匹配 |
| 小米 | 开放平台 | AppID, AppKey | 包名未注册 |
| OPPO | 开放平台 | App Key, Master Secret | 未通过企业认证 |
| vivo | 开发者平台 | App ID, App Key | 测试白名单未添加 |
配置完成后，务必在uniPush控制台的"厂商通道配置"中启用各平台，并填写对应密钥。
常见问题解决方案：
- 华为推送失败：检查AGC控制台是否开通Push Kit服务
- 小米推送收不到：确认测试设备已添加到"测试设备列表"
- 所有厂商推送都失败：检查证书包名/Bundle ID是否与各平台注册信息完全一致
4. 云函数集成与推送代码实战
现在我们来创建实际发送推送的云函数。
4.1 创建推送云函数
- 在HBuilderX中右键uniCloud/cloudfunctions文件夹
- 选择"新建云函数"，命名为"uni-push-demo"
- 勾选"uni-cloud-push"扩展库依赖
4.2 编写推送代码
以下是带详细注释的完整示例：
'use strict'; const uniPush = uniCloud.getPushManager({ appId: "__UNI__XXXXXX" // 替换为你的应用ID }) exports.main = async (event, context) => { // 解析客户端传递的参数 const { alias, title, content, payload } = event try { const result = await uniPush.sendMessage({ "getui_alias": alias, // 使用别名推送 "title": title || '默认标题', "content": content || '您有新消息', "force_notification": true, // 强制展示通知 "payload": JSON.stringify(payload || {}), // 自定义数据 "android_channel_id": "high_importance" // 安卓通知渠道 }) return { code: 0, message: '推送成功', data: result } } catch (e) { return { code: -1, message: '推送失败: ' + e.message } } }4.3 部署与调用
- 右键云函数选择"上传部署"
- 在uniCloud控制台找到该函数，点击"详情"获取调用URL
- 客户端调用示例：
uniCloud.callFunction({ name: 'uni-push-demo', data: { alias: 'user123', // 目标用户别名 title: '订单通知', content: '您有新订单待处理', payload: { // 自定义数据 orderId: '123456', type: 'new_order' } } })5. 客户端消息处理与优化技巧
接收端需要正确处理推送消息和通知栏点击事件。
5.1 基础消息监听
在App.vue的onLaunch中添加：
// 推送消息监听 uni.onPushMessage((res) => { if (res.type === "receive") { // 收到推送内容 console.log('收到推送:', res.data) } else { // 通知栏点击 const payload = JSON.parse(res.data.payload || '{}') // 根据payload类型跳转不同页面 handlePushClick(payload) } })5.2 安卓通知渠道优化
对于安卓设备，可以创建自定义通知渠道提升用户体验：
// 安装DCloud-PushSound插件后 const plugin = uni.requireNativePlugin("DCloud-PushSound") plugin.setCustomPushChannel({ channelId: "order_channel", channelDesc: "订单通知", importance: 4, // 高优先级 enableLights: true, // 呼吸灯 enableVibration: true // 震动 })5.3 性能优化建议
- 批量推送使用
sendMessage的数组参数形式 - 重要消息设置
force_notification: true绕过系统限制 - iOS静默推送添加
content-available: 1字段 - 合理使用
badge角标数字提醒用户
实际项目中，我们发现在华为设备上配置正确的通知渠道后，推送到达率从70%提升到了98%。建议对不同业务场景创建独立的通知渠道，方便用户管理。