UniPush 2.0实战避坑指南：从开通到上线的完整记录

去年接手公司新项目时，产品经理要求在UniApp中实现高效的消息推送功能。经过多方调研，最终选择了UniPush 2.0方案。本以为会一帆风顺，没想到从开通服务到最终上线，踩了无数坑。今天就把这段经历完整记录下来，希望能帮到正在或即将使用UniPush的开发者朋友们。

1. 前期准备：了解UniPush 2.0的核心机制

UniPush 2.0是DCloud与个推深度合作的产物，相比1.0版本有几个关键变化：

• 架构升级 ：从直接调用个推接口变为基于uniCloud的云函数架构
• 成本优化 ：官方宣称将个推的VIP Push服务免费开放给开发者
• 功能增强 ：支持更多厂商通道，提升离线消息到达率

实际使用中发现，虽然号称免费，但仍需支付uniCloud的基础资源费用。根据我的计算，每万次推送的综合成本约为0.0583元，确实比传统方案便宜很多。

重要提示：虽然UniPush 2.0本身不收费，但必须开通uniCloud服务，这部分会产生费用

2. 开通服务：那些官方文档没告诉你的细节

2.1 创建uniCloud项目

首先需要在DCloud开发者中心完成实名认证，这个过程相对简单。但接下来创建uniCloud项目时遇到了第一个坑：

// 错误示例：直接在前端项目目录初始化uniCloud
uniCloud.init({
  provider: 'aliyun',
  spaceId: 'your-space-id',
  clientSecret: 'your-client-secret'
})

// 正确做法：应该先创建uniCloud项目，再关联到现有应用

常见问题排查 ：

• 如果提示"空间不存在"，检查spaceId是否正确
• "权限不足"错误通常是因为没配置好服务空间的角色权限

2.2 厂商通道申请

各厂商的推送服务申请流程差异很大，这里列出主要平台的特别注意事项：

厂商	审核时间	特殊要求	常见驳回原因
华为	1-3天	需要签署隐私协议	应用描述不清晰
小米	3-5天	必须上传签名的APK	包名与申请不一致
OPPO	2-4天	需要企业资质	应用分类选择错误
VIVO	5-7天	需提供《软件著作权证书》	隐私政策链接失效

我在小米平台被驳回了3次，都是因为测试包和正式包签名不一致的问题

3. 云函数开发：从零到URL化的完整流程

3.1 创建推送云函数

在uniCloud控制台新建云函数时，推荐使用以下目录结构：

unipush-service/
├── index.js        # 主逻辑
├── config.json     # 各厂商配置
├── package.json    # 依赖管理
└── lib/            # 工具类

核心代码示例：

// 初始化uniCloud
const uniCloud = require('uni-cloud-sdk')

exports.main = async (event, context) => {
  // 参数校验
  if (!event.title || !event.content) {
    return { code: 400, msg: '标题和内容不能为空' }
  }
  
  // 构建推送消息体
  const pushMessage = {
    title: event.title,
    content: event.content,
    payload: JSON.stringify(event.payload || {}),
    channel: event.channel || 'default'
  }
  
  // 调用uniPush API
  try {
    const res = await uniCloud.push.send(pushMessage)
    return { code: 200, data: res }
  } catch (err) {
    console.error('推送失败:', err)
    return { code: 500, msg: '推送服务异常' }
  }
}

3.2 云函数URL化陷阱

将云函数暴露为HTTP接口时，遇到了几个关键问题：

1. 安全配置 ：

   • 必须设置IP白名单
   • 建议开启请求签名验证
   • 限制调用频率防止恶意攻击

2. 性能优化 ：

   # 冷启动问题解决方案
   $ uniCloud deploy --function unipush-service --trigger http --memory 512 --timeout 30
   

3. 跨域处理 ： 在云函数根目录添加 crossdomain.xml 文件，配置允许的域名列表

4. 客户端集成：那些容易忽略的细节

4.1 初始化配置

正确的初始化顺序应该是：

1. 在 App.vue 的 onLaunch 中注册推送服务
2. 监听设备就绪事件
3. 获取客户端标识(CID)
4. 绑定别名(alias)用于精准推送

示例代码：

<script>
export default {
  onLaunch() {
    // 确保设备准备就绪
    uni.onDeviceReady(() => {
      this.initPushService()
    })
  },
  methods: {
    async initPushService() {
      // 获取推送权限
      const settings = await uni.getPushSettings()
      if (!settings.authorization) {
        await uni.requestPushPermission()
      }
      
      // 初始化推送服务
      uniPush.init({
        appId: 'your-app-id',
        appKey: 'your-app-key'
      })
      
      // 监听消息到达
      uniPush.onMessageReceived(msg => {
        this.handlePushMessage(msg)
      })
    }
  }
}
</script>

4.2 厂商通道验证

如何确认消息确实走了厂商通道？我总结了一套验证方法：

1. 华为通道 ：

   • 查看通知栏图标是否为应用默认图标
   • 在华为开发者后台的"推送报告"中查看送达数据

2. 小米通道 ：

   • 通知会显示"来自小米推送"
   • 可以在通知设置中查看详细来源

3. 通用验证法 ：

   • 关闭应用进程后发送推送
   • 如果仍能收到，说明走了厂商通道

5. 后台对接：Go语言实战示例

虽然UniPush 2.0强调将逻辑放在云函数，但后台系统仍需要调用这些接口。以下是Go语言的对接示例：

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
)

type PushRequest struct {
	Title   string                 `json:"title"`
	Content string                 `json:"content"`
	Payload map[string]interface{} `json:"payload,omitempty"`
	Target  []string               `json:"target,omitempty"`
}

func SendUniPush(apiURL, secret string, req PushRequest) error {
	body, err := json.Marshal(req)
	if err != nil {
		return fmt.Errorf("encode request failed: %v", err)
	}

	httpReq, err := http.NewRequest("POST", apiURL, bytes.NewReader(body))
	if err != nil {
		return fmt.Errorf("create request failed: %v", err)
	}

	// 添加签名头
	timestamp := time.Now().Unix()
	sign := generateSignature(secret, string(body), timestamp)
	httpReq.Header.Set("X-Signature", sign)
	httpReq.Header.Set("X-Timestamp", strconv.FormatInt(timestamp, 10))
	httpReq.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(httpReq)
	if err != nil {
		return fmt.Errorf("send request failed: %v", err)
	}
	defer resp.Body.Close()

	if resp.StatusCode != http.StatusOK {
		return fmt.Errorf("unexpected status: %d", resp.StatusCode)
	}

	return nil
}

性能优化建议 ：

• 使用连接池复用HTTP客户端
• 批量发送时合并请求
• 异步处理发送结果

6. 上线前的最后检查清单

经过两个月的开发和调试，我们总结了一份上线前的检查清单：

1. 厂商通道验证 ：

   • [ ] 所有目标厂商的推送证书已正确配置
   • [ ] 测试过各厂商的离线推送场景

2. 云函数监控 ：

   • [ ] 设置了合理的告警阈值
   • [ ] 日志收集系统正常工作

3. 客户端兼容性 ：

   • [ ] 测试过Android 8+各版本
   • [ ] 验证了不同厂商ROM的表现

4. 压力测试 ：

   • [ ] 模拟过峰值时段的推送量
   • [ ] 验证了消息去重机制

5. 数据统计 ：

   • [ ] 搭建了推送效果分析看板
   • [ ] 设置了关键指标监控

实际项目中，我们在上线前一天发现华为平台的证书即将过期，险些酿成大事故。现在团队养成了每月检查各平台证书有效期的习惯。