更新记录

1.0.0（2026-08-21）

• 首个版本：文本流式 HTTP 客户端插件
• 支持协议：sse / line / jsonl / raw
• 支持方法：GET / POST / PUT / PATCH / DELETE
• 新增跨端纯 UTS 解析引擎 LimeStreamEngine，各端原生只负责「建连 / 拿字节流 / 收尾」，解析与事件派发统一下沉到 UTS 侧
• 新增 connectEventSource(options) => LimeEventSource
• 新增事件：onOpen / onChunk / onMessage / onError / onComplete，以及对应的 off* 解绑与 abort() / close() 中止
• 新增 autoParseJson 选项（jsonl 默认开启，其它协议默认关闭）
• 支持平台：Web、微信小程序、App Android、App iOS、App Harmony

平台兼容性

uni-app(5.14)

uni-app x(5.14)

lime-sse

用于 uni-app x / uni-app 的文本流式 HTTP 客户端插件，支持 SSE / 行文本流 / JSONL / 原始文本多种解析协议。

安装

插件市场导入，在页面引入，自定义基座。

注意

• 本插件基于 UTS 原生能力，建议在导入后先用模拟器 / 真机试跑演示组件 <lime-sse />
• 完成安卓 / iOS 真机测试，确认流式解析与事件回调符合预期后再集成到业务

自定义基座说明：

• 本插件使用 UTS 原生能力，必须在自定义基座中运行，标准基座无法使用
• CLI 项目特别注意：请检查根目录 package.json，确保所有 @dcloudio/* 相关包的版本号一致，且与当前 HBuilderX 版本对齐。版本不一致会导致自定义基座编译失败或运行异常

导入

import { connectEventSource, type LimeEventSource, type ConnectEventSourceOptions } from '@/uni_modules/lime-sse'

TypeScript / uni-app x 项目：上面示例中的 type LimeEventSource、type ConnectEventSourceOptions 以及 : LimeEventSource、: ConnectEventSourceOptions 等类型标注是 TypeScript 专属语法，用于获得类型提示。

纯 JavaScript（uni-app .vue / .js）项目：import type { ... } 不是合法 JS 语法，请勿引入类型、也不要写类型标注。只需引入函数本身即可，类型由运行时自动推断：

import { connectEventSource } from '@/uni_modules/lime-sse'

const es = connectEventSource({
  url: 'http://localhost:8788/sse',
  protocol: 'sse'
})

快速开始

import { connectEventSource, type LimeEventSource, type ConnectEventSourceOptions } from '@/uni_modules/lime-sse'

const options: ConnectEventSourceOptions = {
  url: 'http://localhost:8788/sse',
  method: 'GET',
  protocol: 'sse',
  debug: true,
  headers: {
    'X-Demo-Protocol': 'sse'
  }
}

const es: LimeEventSource = connectEventSource(options)

es.onOpen((evt) => {
  console.log('open', evt.statusCode, evt.headers)
})

es.onChunk((evt) => {
  console.log('chunk', evt.text)
})

es.onMessage((evt) => {
  console.log('message', evt.type, evt.id, evt.data, evt.rawText)
})

es.onError((err) => {
  console.error('error', err.errCode, err.errMsg, err.data)
})

es.onComplete(() => {
  console.log('complete')
})

// 手动停止
es.abort()

API

connectEventSource(options) => LimeEventSource

options 类型为 ConnectEventSourceOptions：

type ConnectEventSourceOptions = {
  url: string
  method?: string | null
  headers?: UTSJSONObject | null
  body?: UTSJSONObject | string | null
  timeout?: number | null
  protocol?: 'sse' | 'line' | 'jsonl' | 'raw' | null
  autoParseJson?: boolean | null
  debug?: boolean | null
}

参数说明：

• url: string 流式接口地址，必填。
• method?: string | null 请求方法，默认 GET。
• headers?: UTSJSONObject | null 自定义请求头。
• body?: UTSJSONObject | string | null 请求体。建议只在 POST / PUT / PATCH / DELETE 时传入。
• timeout?: number | null 超时时间，单位毫秒。App 平台默认 60000。
• protocol?: 'sse' | 'line' | 'jsonl' | 'raw' | null 解析协议，默认 sse。
• autoParseJson?: boolean | null 是否自动把 message 文本解析为 JSON。未传时按协议默认值处理：sse / line 默认 false，jsonl 默认 true。
• debug?: boolean | null 是否输出插件内部调试日志，默认 false。开启后会打印 connect/open/chunk/message/error/complete/abort，其中 chunk 会输出完整文本内容。

返回值：

interface LimeEventSource {
  onOpen(callback): void
  offOpen(): void
  onChunk(callback): void
  offChunk(): void
  onMessage(callback): void
  offMessage(): void
  onError(callback): void
  offError(): void
  onComplete(callback): void
  offComplete(): void
  abort(): void
  close(): void
}

close() 为 abort() 的别名，两者行为一致。

事件说明

onOpen

收到响应头后触发一次。

如果服务端返回 4xx / 5xx，也会先触发 onOpen，随后再触发 onError 和 onComplete。

es.onOpen((evt) => {
  console.log(evt.statusCode)
  console.log(evt.headers)
})

onChunk

每收到一段原始文本就触发一次。无论是哪种协议，都会先走 onChunk。

es.onChunk((evt) => {
  console.log(evt.text)
})

onMessage

仅在 sse / line / jsonl 下触发，raw 不会触发。

• sse: evt.data 保持原始字符串
• line: evt.data 保持原始字符串
• jsonl: evt.data 优先解析为 JSON；解析失败时保留原始字符串
• 显式传 autoParseJson: true/false 时，会覆盖上面的协议默认行为

es.onMessage((evt) => {
  console.log(evt.type)
  console.log(evt.id)
  console.log(evt.data)
  console.log(evt.rawText)
})

onError

网络失败、HTTP 非 2xx、解析失败时触发。

es.onError((err) => {
  console.error(err.errCode, err.errMsg, err.data)
})

onComplete

连接正常结束、发生错误、或手动调用 abort() / close() 后都会触发一次。

es.onComplete(() => {
  console.log('stream finished')
})

协议差异

所有协议都会先触发 onChunk（收到原始文本片段时），区别在 onMessage 的切分与 evt.data 的处理：

sse

按标准 Server-Sent Events 解析。

const es = connectEventSource({
  url: 'http://localhost:8788/sse',
  protocol: 'sse'
})

line

按换行切分，每一行对应一个 message。

const es = connectEventSource({
  url: 'http://localhost:8788/line',
  protocol: 'line'
})

jsonl

按换行切分，每一行按 JSONL / NDJSON 解析。

const es = connectEventSource({
  url: 'http://localhost:8788/jsonl',
  protocol: 'jsonl'
})

覆盖默认解析行为

const es = connectEventSource({
  url: 'http://localhost:8788/sse',
  protocol: 'sse',
  autoParseJson: true
})

const es = connectEventSource({
  url: 'http://localhost:8788/jsonl',
  protocol: 'jsonl',
  autoParseJson: false
})

raw

不做 message 切分，只保留 chunk。

const es = connectEventSource({
  url: 'http://localhost:8788/raw',
  protocol: 'raw'
})

常见用法

POST + JSON 请求体

const es = connectEventSource({
  url: 'http://localhost:8788/sse/post-echo',
  method: 'POST',
  protocol: 'sse',
  headers: {
    'Content-Type': 'application/json'
  },
  body: {
    topic: 'demo',
    userId: 'u_001'
  }
})

发送纯文本请求体

const es = connectEventSource({
  url: 'http://localhost:8788/raw',
  method: 'POST',
  protocol: 'raw',
  headers: {
    'Content-Type': 'text/plain'
  },
  body: 'hello stream'
})

开启调试日志

const es = connectEventSource({
  url: 'http://localhost:8788/sse',
  protocol: 'sse',
  debug: true
})

开启后，插件会在控制台输出连接生命周期日志。chunk 日志会打印完整文本内容，适合排查流式拆包问题；如果响应里包含敏感信息，不建议在生产环境打开。

页面卸载时关闭连接

let es: LimeEventSource | null = null

onUnload(() => {
  es?.abort()
  es = null
})

平台支持

适用场景：

• 标准 SSE（Server-Sent Events）
• 按行文本流（Line）
• JSONL / NDJSON
• 原始文本 chunk（Raw）

平台注意事项

• SSE 协议下默认追加 Accept: text/event-stream 与 Cache-Control: no-cache；line / jsonl / raw 下不强制追加，避免污染非 SSE 请求。
• body 传对象时，会序列化为 JSON 字符串，并默认补 Content-Type: application/json。
• 手动 abort() 不应作为错误处理；如果你只是主动停止连接，请在 onComplete 里做收尾。

错误码

演示组件

插件内置 lime-sse 演示组件（components/lime-sse/lime-sse.uvue），导入后可直接在页面中查看效果：

<lime-sse />