更新记录

1.4.2（2026-09-06）

• 归并 Android 回调稳定性修复：事件统一回到主线程 FIFO 派发，并过滤取消、关闭和重连产生的旧回调，避免旧请求覆盖新连接；版本号保持 1.4.2。
• 2026-09-06：修复 iOS 建立连接和派发事件时可能闪退，以及普通请求头对象、强类型配置和回调未被正确识别的问题；无需修改调用代码，需要重新制作并安装 iOS 自定义基座。
• 2026-09-06：修复取消后仍启动请求、快速重连被旧请求结束事件打断、短暂切换后台后无法恢复和关闭后回调资源未释放的问题；修复仅按事件名结束时的终止条件，拦截非有限及超出范围的数值。App 升级后需更新包含本插件的原生代码，Android 仅更新资源包不能替代原生联编或重新制作自定义基座。
• 2026-09-06：修复 uni-app x Android 示例的函数声明顺序、默认参数及嵌套配置类型，保留连接与自检的既有行为。
• 修复 iOS 动态参数省略 debug / logPayload 时生成 Swift 对空值执行 as! Bool、导致 connectStream 在网络请求启动前闪退的问题；缺省值统一安全回落为 false。
• 修复使用 jsonBody 且未显式设置 Content-Type 时，默认 JSON 请求头因未接收不可变数组返回值而未生效的问题；客户自定义的任意大小写 Content-Type 仍保持不覆盖。
• 优化流解析器的资源上限：按码元单遍消费并即时约束未完成行；SSE 未结束 data、多行换行及持久化 event/id 均按 UTF-8 执行 maxMessageBytes，超限或 JSONL 解析失败后清理状态并锁定解析器，避免旧数据继续派发。
• 修复只包含 id:、不包含 data: 的 SSE 事件更新未同步到后续重连，以及新一轮解析器首个无 id 分片可能清空既有 Last-Event-ID 的问题。
• 修复 iOS URLSessionDataDelegate 的响应头、数据与完成方法在自定义基座中未显式暴露给 Objective-C runtime，导致服务端已返回 HTTP 200、页面却始终收不到 onOpen / onMessage / onComplete 的问题。
• 修复 iOS SSE 使用 CRLF 事件分隔符时，空事件行经两参数 substring 后未稳定触发消息派发，导致 HTTP 200 但 onMessage / onMessageBatch 无消息的问题；LF、Line、JSONL 与 Android 行为保持不变。
• 修复 iOS uni-app 的 reconnect / recovery / batch / terminal 普通 JS 嵌套对象在 ByJs 边界作为 Any 时字段读取失败、全部回退默认值的问题；现收敛为动态 JSON 后继续逐字段归一化与校验。
• 调整示例空闲超时自检窗口，覆盖较慢局域网握手后完整的 1200ms 空闲计时，同时仍仅以真实 9098005 回调作为通过条件。
• 修复 iOS 原生回调分别使用独立异步计时任务时可能打乱 onOpen / onChunk / onMessage / onError / onComplete 顺序的问题；改为单一 FIFO 页面派发队列，在继续规避原生命令栈同步回调闪退的同时保持生命周期顺序。
• 修复 iOS uni-app 调用 connectStream 时，HBuilderX ByJs 对批量回调和普通 JS 对象执行不兼容强转、导致 SIGABRT 闪退的问题；入口统一保留为原始动态对象，再在插件内部恢复强类型配置与回调。
• 修复 iOS 将整个 connectStream 参数声明为 UTSJSONObject 时函数字段在 ByJs 边界变为空、URLSession 已收到 HTTP 200 但页面仍为 HTTP 0 且无消息的问题；入口改为原始动态对象，嵌套配置继续逐字段校验，页面回调通过 UTSCallback / UniCallbackWrapper / JSValue 安全桥与异步 FIFO 交付。
• 修复 iOS 动态 connectStream 参数在逐字段读取时仍经 JSON.stringify / parseObject，导致普通字段可用但回调函数被序列化为空的问题；改由 Swift 直接读取 UTSJSONObject / JSValue / NSDictionary 字段并保留原始函数对象。
• 修复 iOS Swift 动态字段桥对 URL、超时、布尔值和数组等普通配置仍返回 JSValue，导致 UTS 类型判断全部回退、connectStream 在网络启动前卡住且无回调的问题；配置字段现安全拆箱，页面回调字段继续保留 JSValue 交由异步安全桥调用。

1.4.1（2026-08-04）

• 修复 Android 已收到响应头后仍沿用建连阶段读取超时，导致较短 idleTimeoutMs 最迟约 30 秒才触发的问题。
• Android 原生流改用独立空闲计时器：打开流后启动、收到有效字节后刷新，并在完成、失败或主动取消时清理，保持 exactly-once 回调语义。
• 修复 uni-app 与 uni-app x 的 Retry-After 演示场景默认未开启重连，导致 HTTP 429 只结束不展示服务端等待策略的问题。
• Android 原生实现已变化，需重新原生联编、云打包或安装匹配的自定义基座，仅更新 wgt 不足。

1.4.0（2026-07-30）

• 新增默认关闭的 terminal 业务终止帧策略，可按完整消息 data 或 SSE event 识别 [DONE] 等服务端完成信号。
• 新增 onTerminal、完成原因 terminal-message 和指标 terminalMatchCount，明确区分业务正常完成、人工取消、远端结束与错误。
• 支持大小写敏感完整相等、data 优先、可选首尾空白裁剪和 deliverMessage 控制；Raw 没有稳定消息边界，开启时明确返回参数错误。
• 命中终止帧后先刷新批处理，再停止平台传输并完成连接；不触发错误、不安排重连，同一分片后续消息不再交付。
• 诊断只记录是否启用、匹配来源和候选数量，不保存候选值、终止消息或业务正文。
• 测试服务与 uni-app / uni-app x 示例新增业务终止场景；默认关闭时 [DONE] 仍按普通消息交付，现有客户调用保持不变。
• 修复 Android 合并转译时公共环境广播函数与平台公开 API 同名，导致生成 Kotlin 出现无效 __1 函数别名并在 uni-app x 云打包报 Function invocation expected 的问题。
• 公共 App UTS 契约与运行时已变化，使用本版本需重新原生联编、云打包或安装匹配自定义基座，仅更新 wgt 不足。

平台兼容性

uni-app(5.07)

uni-app x(5.07)

lizhao-sse-pro

lizhao-sse-pro 是面向 AI 对话、智能客服、消息推送、日志流和长任务进度的专业 UTS 流式请求插件。一次接入即可在 Android、iOS、HarmonyOS、Web、微信小程序中统一处理 SSE、逐行文本、JSONL 和 Raw 文本流。

插件不是对 EventSource 的简单包装：它支持 POST/PUT/PATCH/DELETE、自定义请求头与请求体、严格 UTF-8 增量解码、首包保护、SSE 标准字段、Last-Event-ID、可控重连、超时、限流和幂等取消。

功能特色

• 四种流协议：sse / line / jsonl / raw，同一套回调处理不同服务端格式。
• 不局限 GET：支持 GET、POST、PUT、PATCH、DELETE，可接 OpenAI 兼容接口、私有 AI 网关和业务流接口。
• 两种请求头写法：兼容 headers 动态对象，同时推荐跨端更稳定的 headerList 强类型数组。
• 首包不丢：所有回调在网络请求发出前完成注册，适配“连接后立即返回第一段”的服务端。
• 完整 SSE 语义：支持 BOM、CR/LF/CRLF、注释心跳、多行 data、event、id、retry 和未知字段忽略。
• UTF-8 分片安全：Android、iOS、HarmonyOS、Web、微信小程序都会保留不完整多字节尾部，中文和 Emoji 不会因网络分片乱码。
• 断线续传：可将最近 id 自动写入下一次请求的 Last-Event-ID。
• 生产级重试：默认关闭，支持最大次数、指数退避、抖动、SSE retry、HTTP Retry-After、状态码覆盖、累计时间预算和远端结束策略；避免 POST 默认重放。
• 网络与前后台恢复：自动感知网络变化，可在 App 回到前台后按策略立即恢复，并在离线或后台期间暂停无意义重试。
• 连接指标：通过 getMetrics() 随时读取连接耗时、首字节、消息、字节、错误、重连和恢复次数。
• 脱敏诊断：exportDiagnostics() 生成可直接交给技术支持的 JSON 报告，不包含 URL 查询参数、请求头值、请求体或消息正文。
• 高频批处理：可按时间窗口或数量合并 chunk/message 回调，减少 AI 高频 token 对页面渲染的压力。
• 业务终止帧：可识别 [DONE] 或自定义 data/event 控制帧，以正常完成原因结束，不再把服务端完成误记为人工取消。
• 生命周期明确：idle → connecting → open → reconnect-wait / closed，abort() 可重复调用，最终完成回调只触发一次。
• 安全边界：默认不打印 URL 查询参数、请求头、Token、请求体或业务消息；可设置缓冲区和单消息上限。
• 微信真实分块：使用 uni.request({ enableChunked: true }) 和 RequestTask.onChunkReceived，不是等待完整响应后伪装流式。
• 无额外网络 SDK：Android 使用 HttpURLConnection，iOS 使用 URLSessionDataDelegate，HarmonyOS 使用 requestInStream，Web 使用 Fetch 流，微信使用 RequestTask。
• HarmonyOS 源码实现：不依赖加密 module.har，规避插件导入或云打包时找不到 HAR 的问题。

适用业务场景

• AI 对话、知识库问答、智能客服逐字输出
• 服务端事件推送、告警、排队状态和任务进度
• 流式日志、设备遥测、后台作业状态
• NDJSON / JSONL 数据管道
• 需要 Authorization、自定义签名头或 POST JSON 的流式接口
• 需要手动取消、自动重连、断线续传或并发多连接的业务

接入方式选择

插件是 API 插件，不包含固定聊天 UI。这样可直接接入你现有的聊天页、Markdown 渲染器、状态管理和业务组件。

安装与运行前准备

1. 在 DCloud 插件市场导入插件，确认目录为 uni_modules/lizhao-sse-pro。
2. 页面始终从插件根目录导入，不要指向 utssdk/index.uts。
3. Android、iOS、HarmonyOS 首次接入或升级原生代码后，需要重新制作并安装自定义基座。
4. Web 无需自定义基座，但服务端必须允许当前站点跨域访问并关闭响应缓冲。
5. 微信小程序无需自定义基座，但必须在微信公众平台配置 HTTPS 合法请求域名；正式版不能依赖开发工具的“忽略域名校验”。
6. 生产接口建议使用 HTTPS，不要把 Token 写死在源码或日志中。

仓库自带本地测试服务：

# 在项目根目录执行；服务默认监听 0.0.0.0:8787，允许局域网真机访问
D:\HBuilderX\plugins\node\node.exe uni_modules\lizhao-sse-pro\example\server\lizhao-sse-pro-test-server.js

也可以使用系统 Node：

node uni_modules/lizhao-sse-pro/example/server/lizhao-sse-pro-test-server.js

测试服务默认监听 0.0.0.0，但控制台只展示安全的本机地址和真机地址提示。服务已内置 Web 示例需要的 CORS 预检与响应头，无需另外安装代理。需要限制监听网卡时可设置 LIZHAO_SSE_TEST_HOST=127.0.0.1；端口可通过 LIZHAO_SSE_TEST_PORT 修改。

最小可运行示例

uni-app 示例

import { connectStream } from '@/uni_modules/lizhao-sse-pro'

const connection = connectStream({
  url: 'https://example.com/events',
  // 回调与参数一次性传入，插件会先注册回调再发起请求。
  onMessage(message) {
    console.log('收到完整事件：', message.data)
  },
  onError(error) {
    console.log('连接失败：', error.errCode, error.errMsg)
  },
  onComplete(event) {
    console.log('连接最终结束：', event.reason)
  }
})

// 页面离开或用户点击停止时调用；重复调用是安全的。
connection.abort()

uni-app x 示例

import {
  connectStream,
  type StreamConnection,
  type StreamMessage,
  type StreamFail
} from '@/uni_modules/lizhao-sse-pro'

let connection: StreamConnection | null = null

connection = connectStream({
  url: 'https://example.com/events',
  protocol: 'sse',
  onMessage: (message: StreamMessage): void => {
    console.log('收到完整事件：' + message.data)
  },
  onError: (error: StreamFail): void => {
    console.log('连接失败：' + error.errCode.toString())
  },
  onComplete: (event): void => {
    console.log('连接最终结束：' + event.reason)
    connection = null
  }
})

微信小程序最小示例

微信小程序仍从插件根目录导入，API 与 App/Web 相同；插件内部会启用 enableChunked 并在 RequestTask 创建后立即注册分片监听。

import { connectStream } from '@/uni_modules/lizhao-sse-pro'

const connection = connectStream({
  // 必须提前配置为微信小程序合法请求域名。
  url: 'https://stream.example.com/events',
  protocol: 'sse',
  onMessage(message) {
    console.log('微信小程序收到事件：', message.data)
  },
  onError(error) {
    console.log('微信小程序连接失败：', error.errCode, error.errMsg)
  },
  onComplete(event) {
    console.log('微信小程序连接结束：', event.reason)
  }
})

// 页面卸载或用户停止时主动取消，避免残留网络任务。
connection.abort()

常见增强示例

POST JSON、自定义请求头和鉴权

import { connectStream } from '@/uni_modules/lizhao-sse-pro'

const connection = connectStream({
  url: 'https://api.example.com/v1/chat/stream',
  method: 'POST',
  protocol: 'sse',
  // 推荐 headerList：Android、iOS、HarmonyOS、Web 的类型行为一致。
  headerList: [
    { name: 'Authorization', value: 'Bearer ' + runtimeToken },
    { name: 'X-Customer-ID', value: customerId }
  ],
  jsonBody: {
    model: 'your-model',
    messages: [
      { role: 'user', content: '你好' }
    ],
    stream: true
  },
  reconnect: {
    // POST 默认不要自动重连，除非服务端提供幂等键并允许安全重放。
    enabled: false
  },
  terminal: {
    // 显式开启后默认匹配 [DONE]，并把它作为控制帧而不是普通消息。
    enabled: true,
    deliverMessage: false
  },
  onMessage: (message): void => {
    console.log(message.data)
  },
  onTerminal: (event): void => {
    console.log('服务端业务完成，命中字段：' + event.source)
  },
  onComplete: (event): void => {
    // 命中终止帧时 reason 为 terminal-message，不会触发错误或自动重连。
    console.log('最终原因：' + event.reason)
  },
  onError: (error): void => {
    console.log('请求失败：' + error.errMsg)
  }
})

终止策略默认关闭，因此旧代码仍会把 [DONE] 当普通 onMessage 交付。只有显式设置 terminal.enabled: true 后才自动完成；如果旧业务必须继续收到控制帧，可设置 deliverMessage: true。终止识别基于完整 SSE/Line/JSONL 消息，Raw 分片边界不稳定，开启时会返回参数错误。

自动重连与 Last-Event-ID

const connection = connectStream({
  url: 'https://example.com/events',
  protocol: 'sse',
  reconnect: {
    enabled: true,
    maxAttempts: 5,
    initialDelayMs: 1000,
    maxDelayMs: 15000,
    multiplier: 2,
    jitterRatio: 0.2,
    useServerRetry: true
  },
  onRetry: (event): void => {
    console.log('第 ' + event.attempt.toString() + ' 次重连将在 ' + event.delayMs.toString() + 'ms 后执行')
  },
  onMessage: (message): void => {
    // 插件会保存 SSE id，并在重连时自动发送 Last-Event-ID。
    console.log(message.id + ': ' + message.data)
  }
})

生产级重试：Retry-After、状态码与累计预算

只有明确传入 reconnect.policy 才会启用增强策略；不传时仍按原有的 SSE retry 或客户端指数退避执行。自动等待优先级为：有效 HTTP Retry-After → SSE retry: → 客户端指数退避。业务调用 connection.reconnect() 始终请求立即恢复。

const connection = connectStream({
  url: 'https://example.com/events',
  protocol: 'sse',
  reconnect: {
    enabled: true,
    maxAttempts: 8,
    initialDelayMs: 1000,
    maxDelayMs: 30000,
    policy: {
      // 429/503 优先遵循服务端 Retry-After，但最长不超过 30 秒。
      respectRetryAfter: true,
      maxRetryAfterMs: 30000,
      // 从首次可重试失败开始计算；成功重连并收到首条业务消息后重新计时。
      maxElapsedMs: 120000,
      retryableStatusCodes: [429, 503],
      // 禁止列表优先，避免鉴权失败被反复请求。
      nonRetryableStatusCodes: [401, 403],
      // 一次性成功流收到消息后正常结束时，不再重复请求。
      remoteEnd: 'before-first-message'
    }
  },
  onRetry: (event): void => {
    console.log(
      '来源=' + event.source +
      '，等待=' + event.delayMs.toString() +
      'ms，剩余次数=' + (event.remainingAttempts ?? 0).toString()
    )
  },
  onError: (error): void => {
    // 9098015 表示下一次等待会超过累计重试时间预算。
    console.log(error.errCode.toString() + '：' + error.errMsg)
  }
})

Retry-After 支持十进制秒数和标准 IMF-fixdate。无效值、过去时间或缺失响应头会安全回退；原始响应头值不会写入诊断报告。状态码列表只覆盖 HTTP 状态分类，不能把参数、协议、UTF-8 或消息大小错误改成可重试。

网络恢复与 App 前后台恢复

先开启 reconnect，再启用恢复策略。插件会自动监听网络变化；App 生命周期需要从 App.vue 显式通知，避免把页面显示误判成整个应用前后台状态。

// App.vue
import { notifyStreamAppState } from '@/uni_modules/lizhao-sse-pro'

export default {
  onShow() {
    // App 回到前台，满足最短后台时长后可立即恢复连接。
    notifyStreamAppState('foreground')
  },
  onHide() {
    // App 进入后台，后续失败会等待前台恢复，不空转重试。
    notifyStreamAppState('background')
  }
}

const connection = connectStream({
  url: 'https://example.com/events',
  reconnect: {
    enabled: true,
    maxAttempts: 5
  },
  recovery: {
    reconnectOnNetworkRestored: true,
    reconnectOnForeground: true,
    foregroundMinBackgroundMs: 1000,
    deferRetryWhileOffline: true,
    deferRetryWhileBackground: true
  },
  onEnvironmentChange: (event): void => {
    console.log('环境变化：' + event.kind + ' / ' + event.networkType + ' / ' + event.appState)
  }
})

高频消息批处理

batch 默认关闭。开启后，只有提供了对应批量回调的类型才会停止逐条回调；例如只提供 onMessageBatch 时，onChunk 仍会逐条触发。

const connection = connectStream({
  url: 'https://example.com/ai-stream',
  batch: {
    enabled: true,
    intervalMs: 16,
    maxItems: 20
  },
  onMessageBatch: (messages): void => {
    // 一批只更新一次响应式状态，降低高频 token 导致的渲染开销。
    const text = messages.map((item) => item.data).join('')
    appendAssistantText(text)
  }
})

指标快照与脱敏诊断

const metrics = connection.getMetrics()
console.log('连接耗时：' + metrics.connectDurationMs.toString() + 'ms')
console.log('首字节：' + metrics.firstByteDurationMs.toString() + 'ms')

// 报告不包含 Authorization/Cookie 值、URL 查询参数、body、chunk 或 message.data。
const diagnosticJson = connection.exportDiagnostics()
console.log(diagnosticJson)

// 需要立即重建当前流时使用；未开启 reconnect 或额度耗尽会返回 false。
const accepted = connection.reconnect('用户点击重新连接')

Line 与 JSONL

// 每个完整文本行触发一次 onMessage。
const lineConnection = connectStream({
  url: 'https://example.com/logs',
  protocol: 'line',
  onMessage: (message): void => console.log(message.data)
})

// 每个非空行必须是合法 JSON；原文在 data，解析结果在 json。
const jsonlConnection = connectStream({
  url: 'https://example.com/items.ndjson',
  protocol: 'jsonl',
  onMessage: (message): void => {
    console.log(message.data, message.json)
  }
})

状态、超时与大小保护

const connection = connectStream({
  url: 'https://example.com/events',
  connectTimeoutMs: 15000,
  idleTimeoutMs: 45000,
  totalTimeoutMs: 0,
  maxBufferBytes: 1024 * 1024,
  maxMessageBytes: 512 * 1024,
  onStateChange: (event): void => {
    console.log(event.previousState + ' -> ' + event.state)
  },
  onChunk: (event): void => {
    // onChunk 适合进度统计；业务通常优先使用 onMessage。
    console.log('累计字节：' + event.receivedBytes.toString())
  }
})

并发连接与统一关闭

import { connectStream, closeAllStreams } from '@/uni_modules/lizhao-sse-pro'

const chatA = connectStream({ url: 'https://example.com/chat/a' })
const chatB = connectStream({ url: 'https://example.com/chat/b' })

// 可单独取消。
chatA.abort()

// 退出账号或销毁业务模块时统一关闭本插件创建的连接。
closeAllStreams()

完整示例源码

• uni-app：uni_modules/lizhao-sse-pro/example/uniapp/index.vue
• uni-app x：uni_modules/lizhao-sse-pro/example/uniappx/index.uvue
• 随插件发布的本地测试服务：uni_modules/lizhao-sse-pro/example/server/lizhao-sse-pro-test-server.js
• 协议分片样本：scripts/fixtures/lizhao-sse-pro-events.json

完整示例不是简单按钮集合，而是面向首次接入客户的“专业流式控制台”：

1. 启动测试服务并按运行环境选择地址。
2. 从快速体验或异常诊断中选择场景，页面自动填充安全参数。
3. 点击开始连接，观察首包耗时、消息数、接收字节、重连次数、Event ID 和事件时间线。
4. 需要调试时再展开高级配置，修改 method、protocol、headers、body、超时、重连和大小限制。

快速体验场景

异常诊断场景

事件时间线区分 open / chunk / message / retry / state / error / complete，默认最多保存 100 条，支持“全部、消息、错误”过滤和自动跟随。页面切换场景、主动取消和卸载都会执行幂等清理，并通过 closeAllStreams() 兜底关闭连接。

README 只保留可复制的关键片段，页面完整模板、状态管理和样式请直接查看上述示例文件。

API 列表

connectStream(options)

说明

创建一个流式 HTTP 请求。函数同步返回连接控制对象，网络事件通过 options 中的回调持续返回。所有回调会在请求发出前保存，避免立即首包丢失。

支持平台

Android / iOS / HarmonyOS / Web / 微信小程序；兼容 uni-app 与 uni-app x。

参数

重连参数

超时、容量、批处理和重连配置的数值必须是有限数，绝对值不能超过 2147483647；各字段的正数或非负数要求仍按参数表执行。不符合范围时通过 9098001 失败回调返回。

生产级重试参数

恢复参数

recovery 中任何自动恢复行为都依赖 reconnect.enabled: true，并共用 maxAttempts 次数上限。

批处理参数

业务终止帧参数

返回值 StreamConnection

回调数据

StreamMessage

StreamOpenEvent

StreamCompleteEvent

StreamTerminalEvent

StreamRetryEvent

StreamMetrics

notifyStreamAppState(state)

说明

在 App 根生命周期中通知插件进入前台或后台。页面级显示隐藏不能完全代表 App 状态，推荐统一放在 App.vue。

参数

返回值

notifyStreamNetworkChange(isConnected, networkType?)

说明

手动广播网络状态。插件内部已通过 uni.onNetworkStatusChange 自动监听，只有自定义网络探针或特殊运行环境无法监听时才需要调用。

参数

返回值

closeAllStreams()

说明

关闭本插件当前创建的全部连接。重复调用安全，适合退出账号、切换环境或销毁全局流服务时使用。

参数

返回值

getStreamCapabilities()

说明

同步返回当前平台能力矩阵。建议在页面展示功能入口前调用，不要仅依赖平台字符串猜测能力。

参数

返回值

错误码

支持平台

权限

自定义基座

• Android、iOS、HarmonyOS 的实现包含原生 UTS/原生辅助代码，首次安装和每次原生代码升级后必须重新制作自定义基座。
• 只修改页面、示例 URL 或普通业务代码时，不需要重新制作自定义基座。
• 仅更新 wgt 或 appResource 不能替换已经编译进旧基座的原生代码。
• Web 与微信小程序不需要自定义基座。

服务端建议

• SSE 响应建议设置 Content-Type: text/event-stream; charset=utf-8。
• 微信小程序服务端必须持续刷新响应分块，建议显式使用 Transfer-Encoding: chunked，不能等完整正文生成后一次性返回。
• 每个 SSE 事件以空行结束；多个 data: 会按换行合并。
• 代理层关闭缓冲，例如 Nginx 可返回 X-Accel-Buffering: no 并按部署策略关闭 proxy buffering。
• 定期发送 : heartbeat 注释行，避免网关把空闲连接关闭。
• 需要续传时发送稳定递增的 id:，并识别客户端 Last-Event-ID。
• POST 自动重连前必须设计幂等键，防止生成任务、扣费或业务写入重复执行。
• 限流服务建议返回 Retry-After；客户端仍应配置合理的最大等待、累计预算和不可重试鉴权状态码。
• 返回内容必须是合法 UTF-8；插件不会用替换字符静默掩盖非法编码。

常见问题

为什么推荐 headerList，仍然保留 headers？

部分 UTS 平台或 uni-app 动态桥接对普通对象的推断存在差异。插件保留 headers 方便旧代码迁移，同时将它归一化为字符串请求头；新项目优先使用 headerList，类型最明确。同名时 headerList 覆盖 headers。

为什么第一条消息偶尔收不到？

常见原因是先连接、成功后才注册监听。lizhao-sse-pro 将 onOpen/onChunk/onMessage/... 全部放入 connectStream(options)，平台层在发起请求前注册原生监听。请不要在 onOpen 之后才动态替换 onMessage。

支持 POST 参数吗？

支持。使用 method: 'POST'，并在 bodyText 与 jsonBody 中二选一。jsonBody 会自动序列化，并在客户未配置时补 Content-Type: application/json; charset=utf-8。

retry 和关闭回调是否真的实现？

已实现。合法的 HTTP Retry-After 优先于 SSE retry: 和客户端退避；onRetry 会区分 retry-after / server / client 及主动恢复来源。onComplete 和兼容的 complete 只在连接最终结束时触发一次，单次失败后仍要重连时不会提前完成。

HarmonyOS 为什么不会出现缺少 module.har？

HarmonyOS 能力直接使用公开 requestInStream 源码实现，插件没有加密 HAR 依赖，也不会生成指向不存在 module.har 的依赖项。

Web 一直没有消息，但 App 正常

依次检查：

1. 浏览器 Network 中是否被 CORS 拦截；
2. 预检 OPTIONS 是否允许实际 Method 和 Authorization 等请求头；
3. CDN/Nginx 是否缓冲了响应；
4. 响应是否真正以分块方式持续发送；
5. 页面 HTTPS 时是否请求了被浏览器拦截的 HTTP 混合内容。

微信小程序为什么没有流式回调？

按顺序检查：

1. 请求域名是否已配置为微信小程序合法 HTTPS 域名；
2. 服务端是否真的持续写入并刷新 Transfer-Encoding: chunked 响应；
3. CDN、网关或 Nginx 是否缓冲了完整响应；
4. 是否在页面卸载、切后台或网络切换后被微信运行环境暂停或回收；
5. 开发工具可用但真机不可用时，是否仍依赖“忽略域名校验”或本机 127.0.0.1。

微信小程序不承诺后台常驻连接。页面离开时应调用 abort()，回到前台后由业务按需要重新建立连接。

为什么默认不自动重连？

流式接口经常使用 POST 创建生成任务或产生计费。网络失败后自动重放可能造成重复提交，因此安全默认值是关闭。GET 推送流可按业务开启；POST 必须先保证服务端幂等。

onChunk 和 onMessage 该用哪个？

• onChunk：网络文本分片，适合统计进度和底层诊断，边界不稳定。
• onMessage：经过 SSE/Line/JSONL/Raw 解析后的业务消息，绝大多数页面应使用它。

批处理会不会导致原有回调失效？

默认不会，batch.enabled 默认为 false。启用后也只接管已经提供批量回调的类型：提供 onMessageBatch 后不再逐条触发 onMessage，但没有提供 onChunkBatch 时 onChunk 仍照常逐条触发。连接结束、错误或重连前会先刷新剩余批次。

诊断报告能直接发给技术支持吗？

可以。报告只包含插件版本、平台、脱敏 URL、请求头名称、非敏感配置、指标和最近 50 条生命周期事件。不会写入查询参数、请求头值、请求体、chunk 文本或 message.data。发送前仍建议按你公司的数据制度再次检查。

真机为什么访问不了本地测试服务？

手机里的 127.0.0.1 指向手机自身。改用电脑局域网 IP，确保同一网络，并允许防火墙访问测试端口。Android 使用 HTTP 明文地址时还要遵守宿主网络安全策略；生产环境建议 HTTPS。

发布前验收建议

发布包内提供自动守卫和测试服务，覆盖：

• BOM、CR/LF/CRLF、多行 data、event/id/retry
• 立即首包、中文/Emoji 跨字节分片
• POST JSON、Authorization 和自定义请求头
• Last-Event-ID、非 2xx、连接中断
• Line、JSONL、Raw、并发连接
• 连接/空闲/总时长超时
• 缓冲区与单消息上限
• 主动取消、重复取消和最终回调一次性
• 微信小程序合法域名、立即首包、UTF-8 跨分片、POST/headers、取消与前后台恢复
• 断网后等待、网络恢复立即重连、后台暂停重试和回前台恢复
• getMetrics() 计数与耗时、exportDiagnostics() 查询参数和凭据脱敏
• onMessageBatch 时间/数量刷新、错误/重连/完成前刷新剩余消息

自动检查不能替代客户真实网关、代理、证书和实体设备验收。上线前请至少用一个真实接口在目标 Android/iOS/HarmonyOS 设备和微信小程序真机上验证首包、中文、取消和弱网恢复。

隐私与安全

• 插件不采集、不上传、不保存客户账号、Token、请求体或流消息。
• debug 默认关闭；即使开启，也默认只输出状态和字节数。
• logPayload 会输出业务文本，仅限本地排障，生产环境不要开启。
• 错误 details 不包含完整 headers、body 或 URL 查询参数。
• Token 应由安全登录态或短期凭证提供，不要硬编码到插件、页面或示例。

作者系列 UTS 插件

以下为已在 DCloud 插件市场上架的作者系列 UTS 插件，可按业务场景组合使用。未列出的插件表示当前未确认公开市场页，后续上架后再补充。