更新记录

1.0.0（2026-10-27） 下载此版本

更新日志

本文档记录项目各版本的变更历史，格式基于 Keep a Changelog，版本号遵循 语义化版本 规范。

[v1.0.0] - 2026-10-27

新增

平台兼容性

uni-app(5.33)

其他

uni-push 2.0 消息推送接入指南

基于 uni-app + Vue3 + uni-push 2.0 官方内置模块，实现 Android / iOS App 端消息推送。

目录

• 项目结构
• 环境要求
• 快速开始
• manifest.json 配置说明
• 核心 API 参考
• 代码结构说明
• 后端 / 开发者中心配置
• 测试流程
• 平台差异处理
• FAQ 常见问题

项目结构

Push-notification/
├── pages/
│   └── index/
│       └── index.vue          # 推送演示页面（clientId 展示、日志面板）
├── static/
│   └── logo.png
├── App.vue                     # 应用入口 + uni-push 核心逻辑
├── main.js                     # Vue3 createSSRApp 入口
├── manifest.json               # uni-app 全局配置（含 Push 模块声明）
├── pages.json                  # 页面路由配置
├── uni.scss                    # 全局 SCSS 变量
├── index.html
├── uni.promisify.adaptor.js
├── CHANGELOG.md                # 更新日志
└── README.md                   # 本文档

各文件职责

环境要求

快速开始

第一步：manifest.json 启用 Push 模块

// manifest.json → app-plus → modules
"modules": {
    "Push": {}
}

第二步：App.vue 初始化推送

<script setup> 中调用 initUniPush()，完整代码见 App.vue。

第三步：关联 uniCloud 服务空间

HBuilderX 中右键项目 → 关联云服务空间或云函数项目 → 选择/创建服务空间。

第四步：DCloud 开发者中心开通 uni-push 2.0

1. 登录 DCloud 开发者中心
2. 找到你的应用（AppID：__UNI__9D8838B）
3. 左侧菜单 uniPush → 开通 uni-push 2.0
4. 配置厂商推送通道（Android 厂商 / iOS APNs 证书）

第五步：打自定义基座测试

HBuilderX → 运行 → 运行到手机或模拟器 → 制作自定义调试基座 → 使用自定义基座运行。

manifest.json 配置说明

完整推送相关配置

{
    "app-plus": {
        "modules": {
            "Push": {}   // 启用官方内置推送模块
        },
        "distribute": {
            "android": {
                "permissions": [
                    // 原有权限保持不变 ...

                    // 以下为 uni-push 新增权限
                    "<uses-permission android:name=\"android.permission.POST_NOTIFICATIONS\"/>",
                    "<uses-permission android:name=\"android.permission.FOREGROUND_SERVICE\"/>",
                    "<uses-permission android:name=\"android.permission.RECEIVE_BOOT_COMPLETED\"/>"
                ]
            }
        }
    }
}

Android 权限说明

核心 API 参考

uni-push 2.0 暴露 4 个核心 API，所有 API 仅在 APP-PLUS 平台可用。

1. uni.getPushClientId()

获取设备唯一推送标识（clientId），向指定设备推送消息时需要此 ID。

uni.getPushClientId().then((res) => {
    console.log(res.clientId)  // 设备唯一标识，字符串格式
}).catch((err) => {
    console.error(err)
})

返回值：

注意事项：

• 首次调用可能返回空字符串，待推送服务连接成功后重新获取即可
• App 从后台切回前台时建议重新调用，防止连接断开
• 必须将 clientId 上报到你的后端服务器，服务端才能向指定设备推送

2. uni.onPushMessage(callback)

注册推送消息监听器，统一接收在线透传和通知栏点击。

const handler = (res) => {
    if (res.type === 'receive') {
        // 应用在线时收到透传消息
        console.log('透传消息:', res.data)
    } else if (res.type === 'click') {
        // 用户点击通知栏消息时触发
        console.log('通知点击:', res.data)
    }
}
uni.onPushMessage(handler)

回调参数：

3. uni.offPushMessage(callback)

取消已注册的推送消息监听。在页面销毁 / 组件卸载时调用，避免内存泄漏。

uni.offPushMessage(handler)

4. uni.createPushMessage(options)

创建本地通知（仅在当前设备显示，不走服务端），用于测试通知栏渲染效果。

uni.createPushMessage({
    title: '通知标题',
    content: '通知内容',
    payload: { type: 'local', from: 'test' },
    success: () => { console.log('本地通知已发送') },
    fail: (err) => { console.error(err) }
})

参数：

代码结构说明

App.vue 初始化流程

App 启动
  └─ onLaunch()
       └─ initUniPush()
            ├─ [Android] requestAndroidNotificationPermission()
            │    └─ Android 13+ 动态申请 POST_NOTIFICATIONS
            ├─ registerPushListener()
            │    └─ uni.onPushMessage(handler)
            │         ├─ res.type === 'receive' → handleTransparentMessage()
            │         └─ res.type === 'click'   → handleNotificationClick()
            └─ getPushClientId()
                 └─ uni.getPushClientId() → 上报后端服务器

App 从后台回前台
  └─ onShow()
       └─ getPushClientId()  // 刷新 clientId

pages/index/index.vue 页面功能

条件编译策略

所有推送 API 调用均使用 uni-app 条件编译包裹：

// 仅在 App 端执行
// #ifdef APP-PLUS
uni.onPushMessage(handler)
// #endif

// 仅在 Android 端执行
// #ifdef APP-PLUS-ANDROID
requestAndroidNotificationPermission()
// #endif

为什么需要条件编译？

• 标准基座不包含 Push 模块，H5 / 小程序运行时调用会报 uni.xxx is not a function
• Android 特有 API（如 plus.android.requestPermissions）在 iOS 上不存在

后端 / 开发者中心配置

Android 厂商推送通道

为了 App 被杀后仍能收到推送，需接入厂商通道。在 DCloud 开发者中心 uniPush → Android 配置：

iOS APNs 推送证书

在 DCloud 开发者中心 uniPush → iOS 配置：

1. Apple 开发者账号创建推送证书（Development + Production 各一份）
2. 导出 .p12 文件并设置密码
3. 上传 .p12 文件 + 证书密码 + Bundle ID

服务端发送推送

uni-push 2.0 提供两种服务端方案：

方案一：uniCloud 云函数（推荐）

// uniCloud 云函数中
const uniPush = uniCloud.getPushManager({ appId: '__UNI__9D8838B' })

uniPush.sendMessage({
    push_clientid: '设备clientId',
    title: '推送标题',
    content: '推送内容',
    payload: { url: '/pages/detail/index?id=123' }
})

方案二：DCloud 推送 REST API

POST https://api-push.dcloud.net.cn/push/message
Authorization: Basic base64(appkey:appsecret)
Content-Type: application/json

{
    "appid": "__UNI__9D8838B",
    "push_clientid": "设备clientId",
    "title": "推送标题",
    "content": "推送内容"
}

测试流程

1. HBuilderX 打开项目
        │
2. 右键 → 关联 uniCloud 服务空间
        │
3. 制作自定义调试基座
        │  HBuilderX → 运行 → 运行到手机 → 制作自定义调试基座
        │  （勾选 Android / iOS 平台，等待云打包完成）
        │
4. 真机运行（使用自定义基座）
        │  首页打开 → 看到 ClientID
        │  点击「复制」保存 clientId
        │
5. DCloud 开发者中心测试推送
        │  uniPush → 在线推送 → 粘贴 clientId → 发送
        │
6. 验证结果 ✅
   ├─ App 在线 → 首页日志面板显示「透传消息」
   ├─ App 后台 → 通知栏弹出通知
   └─ App 被杀 → 点击通知后首页日志显示「通知点击」

平台差异处理

FAQ 常见问题

Q1：标准基座收不到推送？

原因：标准基座是 DCloud 预编译的通用包，不包含 Push 模块。

解决：必须制作自定义调试基座（HBuilderX → 运行 → 制作自定义调试基座），或直接云打包。

Q2：uni.getPushClientId() 返回空？

可能原因：

1. 未使用自定义基座，Push 模块未加载
2. 网络不通，推送服务尚未连接
3. uniCloud 服务空间未关联

排查步骤：

1. 确认运行的是自定义基座（启动时会显示「自定义基座」标识）
2. 等待 3-5 秒后再次调用，或检查 onShow 生命周期中是否重新获取
3. HBuilderX 中右键项目 → 确认已关联 uniCloud 服务空间
4. 查看控制台是否有 [uni-push] 推送监听器注册完成 日志

Q3：通知栏收不到推送？

Android 排查：

1. 确认 POST_NOTIFICATIONS 权限已授予（系统设置 → 应用管理 → 通知 → 允许）
2. 确认厂商通道已在 DCloud 开发者中心正确配置
3. 部分国产 ROM 需要在系统设置中手动开启「自启动」和「后台弹出界面」

iOS 排查：

1. 确认 .p12 证书上传正确（Bundle ID 匹配当前 App）
2. 确认通知权限已开启（系统设置 → 通知 → 允许通知）

Q4：App 被杀后收不到推送？

这是最常见问题：

Q5：uni.onPushMessage 没有触发？

1. 确认监听代码在 onLaunch 或 onMounted 中执行（而非条件不满足的分支）
2. 确认使用的是自定义基座
3. 确认推送消息已经到达设备（通知栏有没有显示）
4. 透传消息只有 App 在前台在线时才会回调；通知点击需要用户实际点击通知栏

Q6：H5 / 小程序端为什么调 uni.getPushClientId() 报错？

原因：uni-push 2.0 仅支持 App 端。

解决：用条件编译包裹所有推送 API 调用：

// #ifdef APP-PLUS
uni.getPushClientId().then(...)
// #endif

Q7：如何跳转到指定页面？

在服务端推送的 payload 中携带页面路径，通知点击后根据 payload 跳转：

// App.vue 中 handleNotificationClick
function handleNotificationClick(data) {
    const payload = data.payload || {}
    if (payload.url) {
        uni.navigateTo({ url: payload.url })
    }
}

服务端推送时：

{
    "payload": {
        "url": "/pages/detail/index?id=123"
    }
}

相关链接

License

本项目基于 uni-app 官方内置 Push 模块，遵循 uni-app 开源协议。