更新记录

1.0.0（2026-08-20） 下载此版本

• 首发
• iOS：NSURLSession + NSURLSessionDataDelegate 原生实现（主队列回调、base64 双向编解码、session invalidate 生命周期管理）
• Android：HttpURLConnection + BufferedReader 逐行流式读取
• 微信小程序：wx.request enableChunked + onChunkReceived
• 原生链路异常自动降级 plus.net.XMLHttpRequest
• 主动中断（abort）与资源清理

平台兼容性

uni-app(5.0)

uni-app x(5.0)

native-sse

跨平台 SSE（Server-Sent Events）客户端，专为 AI 流式对话等场景打造。

App 端基于 NativeJS 直连原生 API 实现（不依赖 WebSocket / 轮询），流式数据实时逐块接收。

平台兼容

• 依赖条件编译，需 HBuilderX 编译运行（自定义基座 / 云打包均可，无需原生插件）
• 微信小程序需基础库 2.20.1+（enableChunked）
• vue3 已验证；vue2 理论兼容未验证

快速开始

import SSE from '@/uni_modules/native-sse'

const conn = SSE.connect({
  url: 'https://example.com/api/chat/stream',
  method: 'POST',
  headers: {
    Authorization: 'Bearer xxx'
  },
  body: JSON.stringify({ message: '你好' }),
  onmessage(event) {
    // event = { event: 'message', data: '...' }
    console.log('收到消息', event.data)
  },
  onerror(err) {
    console.log('出错', err)
  },
  onclose() {
    console.log('连接关闭')
  }
})

// 需要时主动中断
conn.abort()

API

SSE.connect(options) → { abort() }

返回 { abort() }，调用 abort() 主动断开连接（iOS 端会同时释放原生 delegate）。

消息格式要求

服务端响应需为标准 SSE 格式（Content-Type: text/event-stream）：

event: message
data: {"content":"你好"}

event: message
data: {"content":"，"}

解析逻辑：以空行（\n\n）分隔事件，事件内按行解析 key: value；仅当 event 和 data 字段同时存在时触发 onmessage。

App 端实现说明（NativeJS 踩坑记录）

iOS 端在真机/模拟器上反复调试后沉淀的关键结论，供二次开发者参考：

1. delegateQueue 必须传主队列（NSOperationQueue.mainQueue）。传 null 时系统创建后台串行队列，delegate 回调在后台线程触发，NJS 桥接无法路由回 JS——现象为 task.state=running 但零回调。

2. 字符串与原生互传必须走 base64。NJS 会基于运行时类型（isKindOfClass:NSString）把一切 NSString 及其子类的方法返回值自动转成 JS String，无论方法签名声明返回 NSString* 还是 id，转换后丢失对象身份无法继续调 OC 方法。因此：

   • 发送方向：utf8ToBase64（纯 JS）→ NSData initWithBase64EncodedString:options:（参数位自动转换安全，返回 NSData 保持 JSBObject）
   • 接收方向：NSData base64EncodedStringWithOptions: 返回值自动转 JS String（base64 文本）→ base64ToUtf8 纯 JS 解码

3. 不实现 didReceiveResponse:completionHandler:。该代理方法携带 OC block 参数，NJS 无法可靠调用；delegate 缺省此方法时系统默认行为即 allow，数据直接流入 didReceiveData。HTTP 状态码校验移至首个数据块（dataTask.response.statusCode）。

4. session 生命周期：NSURLSession 会 retain delegate，连接结束后必须 invalidateAndCancel / finishTasksAndInvalidate 才能释放，didBecomeInvalidWithError: 回调后才是安全的对象清理时机。

5. NJS 对象防 GC：连接期间所有 NJS 引用由闭包持有，防止 GC 提前释放 OC 对象导致悬垂崩溃；plus.ios.implements 合成的 delegate 不做 deleteObject（retain/release 不稳定），仅解除 JS 引用。

反馈

有问题欢迎在插件市场评论区留言或提 issue。