uni-app x 云函数中间状态通知通道uniCloud.SSEChannel 完整指南【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app导读uniCloud.SSEChannel是 uni-app / uni-app x 自 HBuilderX 4.71 起新增的云端消息通道 API用于解决云函数执行长时间任务时客户端无法感知任务进度的问题。本指南以 docs/api/unicloud/sse-channel.md 为主体结合仓库内 uni-push 文档与 manifest 配置说明完整讲解通道的开启前提、客户端 API、云函数 API、完整代码示例与底层实现原理帮助开发者掌握云函数 → 客户端的实时中间状态推送能力。一、为什么需要 SSEChannel云函数长任务的状态盲区1.1 场景痛点在常规 Web 开发中服务端可以向响应流多次写入数据Server-Sent Events / Chunked 响应实现边处理边推送。但云函数serverless的执行模型是一次请求、一次响应不支持向响应流多次写入数据。这带来一个现实问题云函数在执行长时间任务如大文件处理、批量数据清洗、AI 模型推理、多步骤聚合查询时客户端发起uniCloud.callFunction后只能干等最终返回值无法获知云端任务是否仍在正常执行、执行到了哪一步。用户无法判断卡住还是正在跑很可能直接放弃等待、刷新页面重新发起调用从而重复消耗云函数资源甚至引发超时重试导致的重复计算。1.2 解决方案基于 uni-push 2.0 的消息通道由于云函数不支持流式写响应uni-app x 采用了一条替代通道基于 uni-push 2.0 实现客户端与云函数之间的实时消息下发。uni-push 2.0 本身提供在线 socket 下行服务App、小程序、Web 端只要在线服务器即可向其推送消息详见 docs/uni-push/v2.mdSSEChannel 借用这条下行通道让云函数在任务执行过程中向客户端多次写入中间状态/中间结果任务结束再发送结束信号对客户端来说SSEChannel 以类似 EventSource / WebSocket 的事件模型open/message/end/close/error暴露使用体验接近标准 SSE。1.3 关联场景uni-ai x 的 LLM 流式输出在 uni-app x 中使用 AI 大模型时若通过云函数中转流式返回 token持续保持云函数活跃会产生更多费用。因此官方在uni-ai x中提供了另一条路线云端返回临时 token由客户端直连 LLM 接收流式数据既节省云函数运行费用也提供了完整的客户端开源代码可通过 DCloud 插件市场检索uni-ai x获取。当需求是云函数需要边算边报进度时使用 SSEChannel当需求是大模型流式返回时优先考虑 uni-ai x 的直连方案两者适用场景互补。二、使用前置条件开通 uni-push 2.0 与模块配置SSEChannel 依赖 uni-push 2.0使用前必须完成以下准备2.1 开通 uni-push 2.0需先在 uniCloud 控制台开通 uni-push 2.0 服务具体开通流程见 docs/uni-push/v2.md。uni-push 2.0 是 DCloud 推出的全端统一推送服务在线推送App、Web、小程序端通过 socket 实时下行离线推送App聚合华为、小米、OPPO、VIVO、魅族、荣耀、Google FCM 等厂商通道云端一体服务端基于 uniCloud无需自建推送服务器。2.2 uni-app x 项目manifest.json 配置 uni-push 模块uni-app x 项目使用 SSEChannel 时需要自行将 uni-push 模块配置到 manifest.json 内uni-app 普通项目同样需要在 manifest 中启用。各平台配置方式如下。Android 平台在app-android - distribute - modules下添加uni-push节点可按需勾选厂商推送 SDK源码视图示例详见 docs/collocation/manifest-android.md{ app-android: { distribute: { modules: { uni-push: { hms: {}, // 华为厂商推送SDK oppo: {}, // OPPO厂商推送SDK vivo: {}, // VIVO厂商推送SDK xiaomi: {}, // 小米厂商推送SDK meizu: {}, // 魅族厂商推送SDK honor: {}, // 荣耀厂商推送SDK fcm: {} // Google FCM推送SDK } } } } }若不在 manifest 中显式勾选云端打包会根据摇树结果自动决定是否包含 uni-push 模块并依据 uni-push 后台配置的离线推送厂商通道自动添加对应 SDK。HarmonyOS 平台在modules下添加uni-push节点详见 docs/collocation/manifest-harmony.md{ modules: { uni-push: {} } }2.3 自定义基座开发期间需要打包自定义基座进行测试。因为 SSEChannel 依赖 uni-push 原生模块标准基座HBuilderX 自带的公共测试基座不包含项目专属的模块配置必须通过制作自定义调试基座将 manifest 中的 uni-push 配置打入基座后才能在真机/模拟器上验证通道功能。注意配置或修改 manifest.json 中的可选模块后需重新提交云端打包/制作自定义基座才能生效。三、客户端 APISSEChannel(options)3.1 构造函数new uniCloud.SSEChannel(options?): SSEChanneloptions为可选的初始化参数默认即可满足大多数场景。从接口定义看SSEChannel 实例在未开启前不携带可序列化的通道标识必须先调用open()建立通道。3.2 实例方法与事件总览仓库内 docs/api/unicloud/README.md 给出了 SSEChannel 的完整接口定义方法如下| 方法 | 签名 | 说明 | | :- | :- | :- | |open()|open(): Promisevoid|开启通道。只有开启之后才能把 SSEChannel 实例传入云函数 | |toJSON()|toJSON(): { appId: string; pushClientId: string; seqId: string }| 将通道序列化为可传输的 JSON 结构内含appId、pushClientId、seqId三个字符串字段 | |close()|close(): void| 关闭通道 | |on()|on(event: string, callback: (message: string) void): void| 监听事件message 等 | |off()|off(event: string, callback: (message: string) void): void| 取消监听事件 |兼容性Web、微信小程序、Android、iOS、HarmonyOS 五个端均自HBuilderX 4.71起支持对应 docs/release.md 中新增 API 支持 uniCloud.SSEChannel的版本记录。3.3 通道生命周期与序列化原理从接口结构可以推断通道的运行机制open()成功后通道内部通过 uni-push 在客户端建立一条可下行的 socket 会话并生成唯一的通道标识toJSON()返回的{ appId, pushClientId, seqId }正是这条会话的路由信息appId标识应用、pushClientId标识 uni-push 客户端实例、seqId标识本次通道会话的序列号客户端将实例直接作为callFunction的data参数传入框架会自动调用toJSON()完成序列化云函数端再通过uniCloud.deserializeSSEChannel反序列化还原出可写通道云端通过 uni-push 在线 socket 下行通道将消息推送回该客户端客户端触发对应事件。3.4 客户端事件| 事件 | 回调签名 | 触发时机 | | :- | :- | :- | |open|() void| 通道开启成功 | |message|(message?: any \| null) void| 收到云端通过sseChannel.write写入的中间消息 | |end|(message?: any \| null) void| 云端调用sseChannel.end结束通道可携带结束消息 | |close|() void| 通道关闭 | |error|(error: UniCloudError) void| 通道出错可通过error.message获取错误描述 |要点message/end回调中的message可能是任意类型云端写入的原始值客户端需要自行as为实际类型后再使用目标语言是 JS 时云端end未传参的情况下回调收到的值可能为undefined。四、客户端完整代码示例以下示例来自 docs/api/unicloud/sse-channel.md完整演示了创建通道 → 监听事件 → 开启通道 → 传入云函数的全流程async function receiveMessage() { const sseChannel new uniCloud.SSEChannel() sseChannel.on(message, (message?: any | null) { console.log(message: (message as string)) // message可能是任意类型需要自行as为实际类型再使用 }) sseChannel.on(end, (message?: any | null) { console.log(end: message) // message可能是任意类型需要自行as为实际类型再使用。此处在云端end事件返回了null。目标语言是js时可能会返回undefined }) sseChannel.on(open, () { console.log(sseChannel open) }) sseChannel.on(close, () { console.log(sseChannel close) }) sseChannel.on(error, (error: UniCloudError) { console.log(sseChannel error: error.message) }) await sseChannel.open() // 必须await通道开启才可以将sseChannel传入云函数 const res await uniCloud.callFunction({ name: sse, data: { sseChannel } }) console.log(res) }关键注意事项务必await sseChannel.open()只有等通道真正建立open事件已触发、toJSON()可返回有效路由信息之后才能把sseChannel实例放入data传入云函数否则云端反序列化拿不到有效通道标识消息将无法送达。事件要在open()之前注册先on(...)再open()避免漏掉开启瞬间即到达的消息。sseChannel直接作为data字段传入即可无需手动调用toJSON()转换——框架会自动处理序列化。五、云函数 API反序列化与消息写入5.1 反序列化消息通道将客户端传入的 sseChannel 对象JSON 字符串反序列化为可写消息的 SSEChannel 对象uniCloud.deserializeSSEChannel(sseChannelObj: string): SSEChannel参数sseChannelObj来自event中客户端传入的sseChannel字段云端收到的是其toJSON()序列化结果。5.2 sseChannel.write向客户端发送一条中间消息可多次调用实现边执行边上报进度sseChannel.write(message: any): Promisevoidmessage为任意类型字符串、对象、数字等均可客户端message事件回调中收到的就是该值。5.3 sseChannel.end结束消息通道可携带一条结束消息sseChannel.end(message: any): Promisevoid调用后客户端触发end事件通道随之关闭触发close。message参数可选。六、云函数完整代码示例以下示例来自原文档演示连续写两条消息 → 延时 300ms 后结束通道 → 返回结果的完整流程use strict; exports.main async (event, context) { const sseChannelObj event.sseChannel const sseChannel uniCloud.deserializeSSEChannel(sseChannelObj) return new Promise(async (resolve, reject) { await sseChannel.write(message1) await sseChannel.write(message2) setTimeout(async () { await sseChannel.end() resolve({ errCode: 0 }) }, 300) }) };要点分析从event取通道客户端在data.sseChannel传入的通道在云端event.sseChannel中接收先反序列化再使用异步写入write/end均返回Promise建议await等待写入完成再继续避免消息乱序返回最终结果end结束通道后仍可正常resolve云函数返回值客户端callFunction的res会拿到该结果——通道消息与函数返回值是并行的两条链路互不冲突真实业务中的用法将示例中的两条write替换为任务各阶段的进度上报例如已下载 → 正在处理 → 处理完成客户端即可据此渲染进度条或分步日志。七、典型应用流程串联将客户端与云函数两端代码串起来一次完整的 SSEChannel 调用流程如下客户端new uniCloud.SSEChannel()并注册open/message/end/close/error事件await sseChannel.open()建立通道uni-push 在线 socket 会话就绪客户端callFunction调用云函数data携带sseChannel自动序列化为{ appId, pushClientId, seqId }云函数uniCloud.deserializeSSEChannel(event.sseChannel)还原通道任务执行中多次await sseChannel.write(...)上报进度客户端message事件实时收到进度并更新 UI云函数任务完成调用sseChannel.end(...)并返回最终结果客户端收到end→close整个通道生命周期结束。该流程适用于任何需要云端长任务进度回传的场景批量导入导出、视频转码/压缩、报表生成、AI 任务队列、多步骤流程编排等。八、使用建议与边界说明通道与推送的关系SSEChannel 的消息下发依赖 uni-push 的在线 socket 通道见 docs/uni-push/v2.md客户端需保持在线才能实时收到消息这是云函数通知客户端的替代通道不等同于厂商离线推送。资源开销考量通道建立与消息下发会消耗 uni-push 与云函数资源中间状态上报应控制频率如每完成一批任务上报一次避免高频小消息造成不必要的调用开销。大模型流式场景如本文 1.3 节所述若目的是接收 AI 大模型的流式 token优先考虑uni-ai x的云端返回临时 token、客户端直连 LLM方案可避免云函数长时间活跃产生额外费用。版本与平台限制SSEChannel 自 HBuilderX 4.71 起支持 Web、微信小程序、Android、iOS、HarmonyOSuni-app x 项目必须自行在 manifest.json 配置 uni-push 模块且开发调试需使用自定义基座。延伸阅读docs/api/unicloud/sse-channel.md本主题原始文档docs/api/unicloud/README.mduniCloud 客户端 API 总览含 SSEChannel 完整方法签名与兼容性表docs/uni-push/v2.mduni-push 2.0 开通与原理docs/collocation/manifest-android.mdAndroid 平台 uni-push 模块配置docs/collocation/manifest-harmony.mdHarmonyOS 平台 uni-push 模块配置docs/release.mdHBuilderX 4.71 版本中 SSEChannel 的新增记录【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
