AI 聊天接口的流式返回处理起来比大多数人想的要麻烦。尤其是放在 H5 页面里既要照顾手机性能又得搞定中文乱码、滚动卡顿、断线重连这一堆问题。这篇东西是我自己在几个 AI 聊天项目里摸爬滚打攒下来的经验从网络协议选型到前端代码落地再到真机上的坑一次性写透希望对正在搞类似功能的同学有帮助。1. 为什么 AI 聊天必须用流式数据1.1 非流式请求的3 秒魔咒先设想一个场景用户在聊天框里输入帮我写一封辞职信然后点击发送。如果前端用的是普通 fetch那么请求发出后用户面对的是一个无休止的 loading 动画。大模型生成一段完整回复通常需要几秒甚至十几秒这段时间里用户只能干等。更难受的是AI 生成文本的速度并不均匀——开头几个字很快中间可能因为计算复杂而卡顿几秒最后又突然加速。在一次真实测试里某对话模型生成 500 个字符的回复总耗时约 8 秒但中间有 4 秒完全没动静。用户盯着正在输入的动画完全不知道是网络断了还是模型在思考焦虑感极强。这根本不是产品体验是折磨。1.2 流式方案的本质边算边传流式数据的思路完全不同。它允许服务端生成多少就传多少客户端收到多少就展示多少。用户点击发送后几百毫秒内就能看到你字、好字一个一个蹦出来。从产品角度看这种打字机效果不仅大幅降低了感知延迟还给用户一种AI 正在认真思考的参与感。实测下来同样是生成 500 字流式方案的首字延迟能压到 0.8 秒以内用户体感上的等待时间几乎消失。前端领域处理这类数据绕不开两个关键技术点一个是传输协议的选型另一个是流式数据的解析。传输层面H5 页面里主流方案就三种SSE、WebSocket、以及 fetch 配合 ReadableStream 手动读取。你要先把这三者的定位搞清楚后续代码才能写得顺手。2. 流式传输的技术选型2.1 SSE大模型默认的第一选择SSE 全称 Server-Sent Events是 HTTP 协议上的一种服务端推送方案。它和 WebSocket 最大的区别在于它是单向的——只能服务端往客户端发客户端想说话得另起一个普通请求。这在 AI 聊天场景里反而成了优点用户发消息本就是一次性操作根本不需要双向长连接服务端只需要把模型生成的内容持续推给浏览器即可。大模型厂商自己也很偏爱 SSE。OpenAI 的接口默认就支持streamtrue返回的是text/event-stream格式。国内不少模型服务也保留了同样的兼容格式。后端不用做太多额外处理前端也更省心。使用 SSE 最简单的方式是直接用EventSource这个原生 APIconst source new EventSource(/api/chat/stream?message你好); source.onmessage (event) { console.log(收到数据, event.data); };这个 API 自带断线重连机制非常省事。但问题也很明显EventSource只能通过 GET 请求发送没法自定义请求头跨域配置也比较死板不能传 token不能置复杂参数。所以在实际 AI 聊天项目中我几乎不用原生EventSource而是用 fetch 自己解析 SSE 数据流。2.2 WebSocket双向交互的进阶方案WebSocket 就复杂得多它是全双工通信客户端和服务端都能随时发消息。如果你做的不只是简单的问答还需要场景里有持续的双向数据交互比如AI 回复过程中用户频繁打断修改消息、服务端主动推送日志或状态这类需求WebSocket 才是合适的方案。用 WebSocket 做流式聊天核心伪代码一般是这样的function connectChatSocket() { const ws new WebSocket(wss://api.example.com/chat); ws.onopen () { // 发送初始化消息 ws.send(JSON.stringify({ type: init, sessionId: xxx })); }; ws.onmessage (event) { const data JSON.parse(event.data); if (data.type delta) { // 增量文本 appendText(data.content); } else if (data.type done) { // 生成完成 setStreaming(false); } }; }但 WebSocket 对服务器要求高一些得维护长连接状态还得处理心跳包检测。如果你只是做对话生成没有强双向需求我建议不要为了显得高级而上 WebSocket。2.3 fetch ReadableStream最灵活的低层方案这是我在多个正式项目里最终采用的方案。它本质上是手动读取 HTTP 响应体里的数据流兼容性极好不依赖额外的服务端协议直接解析标准 SSE 数据格式即可。fetch 返回的response.body就是一个ReadableStream你可以通过它的getReader()方法一点点读取数据块。核心代码如下const response await fetch(/api/chat/stream, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ message: 你好 }) }); const reader response.body.getReader(); const decoder new TextDecoder(utf-8); while (true) { const { done, value } await reader.read(); if (done) break; const chunk decoder.decode(value, { stream: true }); // chunk 是原始的字节数据块需要进一步解析 parseChunk(chunk); }这套方案的优势在于你可以完全掌控请求头、请求体、取消方式和解析逻辑。前面提到的EventSource做不到的事它全都能做。缺点是你需要自己处理整个流式解析过程这一点绕了一圈还是会在实际操作中遇到不少细节问题我会在下面拆开讲。3. 前端核心实现解析流式数据与打字机效果3.1 搭建一个极简聊天容器先把页面结构搭好。H5 场景下我只推荐用flex布局实现一个下方固定输入框、中间滚动消息区的聊天界面div classchat-container div classmessage-list idmessageList !-- 动态渲染消息 -- /div div classchat-input-area input idinput typetext placeholder输入你的问题... / button idsendBtn发送/button /div /div.chat-container { display: flex; flex-direction: column; height: 100vh; } .message-list { flex: 1; overflow-y: auto; -webkit-overflow-scrolling: touch; } .chat-input-area { flex-shrink: 0; padding: 12px; display: flex; gap: 10px; }一个基础但够用的骨架就是上面这样。注意-webkit-overflow-scrolling: touch这个属性iOS 上如果缺少它列表滚动会非常生涩这是老生常谈的 H5 优化点了。3.2 核心fetch 流式读取数据现在看核心的数据读取逻辑。我封装了一个streamChat函数接收用户消息然后完整走完请求和流式解析。这里要提前设计好回调函数让外部 UI 能实时感知数据状态方便驱动界面更新async function streamChat({ message, onDelta, onDone, onError }) { const controller new AbortController(); try { const response await fetch(/api/chat/stream, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ message }), signal: controller.signal }); if (!response.ok) { throw new Error(请求失败${response.status}); } const reader response.body.getReader(); const decoder new TextDecoder(utf-8); let buffer ; // 用于积攒不完整的 SSE 数据 while (true) { const { done, value } await reader.read(); if (done) break; buffer decoder.decode(value, { stream: true }); // 按换行符分割SSE 协议每行是一条数据 const lines buffer.split(\n); // 最后一行可能是不完整的重新放回 buffer buffer lines.pop(); for (const line of lines) { const trimmed line.trim(); if (trimmed.startsWith(data:)) { const data trimmed.slice(5).trimStart(); if (data [DONE]) { onDone onDone(); return; } onDelta onDelta(data); } } } onDone onDone(); } catch (err) { if (err.name AbortError) { // 用户主动取消不算错误 console.log(已取消请求); } else { onError onError(err); } } }这段代码有几个关键点要解释清楚。第一buffer的作用。网络上数据包是分块到达的后端可能一次发送半行数据也可能一次发送好几行。如果不加 buffer 直接解析很容易丢数据。我的处理逻辑是先按\n分割把最后一段重新放回 buffer因为它极可能是不完整的等下一批数据到达时自动拼上再解析。有些同学在这块偷懒直接 split就会遇到偶发的数据丢失或乱码。第二TextDecoder为什么要传{ stream: true }。这个参数告诉解码器当前字节流是连续的遇到不完整的 UTF-8 字符时先存入缓冲等下一段数据来了再补全。如果不传这个参数中文在流式解码时一定会出现乱码这几乎是新手踩坑第一名。3.3 解析多种格式的数据真实项目中后端返回的 SSE 数据格式不一定都长一样的。最常见的是只带data字段的文本增量但也有的会返回 JSON 结构里面包含role、content、finishReason等信息。为了应对这种情况我把解析逻辑单独抽出来加一个硬编码的容错function parseSSELine(line) { if (!line.startsWith(data:)) return null; const raw line.slice(5).trim(); // 先尝试按 JSON 解析 try { const json JSON.parse(raw); if (json.content) return json.content; if (json.delta json.delta.content) return json.delta.content; return null; } catch { // 解析失败说明返回的是纯文本片段 return raw; } }这样不管是data: 你好这种纯文本格式还是data: {content:你好}这种 JSON 格式一条解析函数都能处理。如果raw是[DONE]或[END]这样的结束标记那就在上层判断处理掉。3.4 打字机效果的节流流式接口源源不断地推送数据如果每次收到一个增量片段就立刻渲染到 DOMH5 页面频繁操作 DOM极容易造成卡顿。尤其在中低端 Android 机器上渲染频率和后台合成线程一冲突页面直接掉帧。我处理这个问题是引入了一个渲染队列机制简单说就是数据到达时先放进队列然后以固定频率比如 50ms 一次把队列里的内容批量刷新到页面。这样可以显著减少 DOM 操作次数。参考实现如下class StreamingRenderer { constructor({ messageElement, flushInterval 50 }) { this.messageElement messageElement; this.flushInterval flushInterval; this.pendingContent ; this.timer null; } push(text) { this.pendingContent text; this._startTimer(); } _startTimer() { if (this.timer) return; this.timer setInterval(() { if (this.pendingContent) { this.messageElement.textContent this.pendingContent; this.pendingContent ; } this.flushTimer setTimeout(() { clearInterval(this.timer); this.timer null; }, 100); }, this.flushInterval); } done() { // 最后彻底刷新一次 if (this.timer) { clearInterval(this.timer); this.timer null; } if (this.pendingContent) { this.messageElement.textContent this.pendingContent; this.pendingContent ; } } }这里有个细节flushInterval我一般设置成 50ms。太快了效果不明显太慢了比如 100ms会感觉打字停顿。实测中 40~60ms 这个区间观感最好。另外注意messageElement.textContent的累加方式适合纯文本型回复。如果回复里需要嵌套 HTML比如要渲染代码块或链接就得改成innerHTML形式但那样要警惕 XSS 风险需要做安全过滤。自动滚动这块我倾向于只在用户没有手动上滑查看历史消息时才自动滚动。实现思路是这样const listEl document.getElementById(messageList); let isPinnedToBottom true; listEl.addEventListener(scroll, () { const distanceToBottom listEl.scrollHeight - listEl.scrollTop - listEl.clientHeight; isPinnedToBottom distanceToBottom 40; }); // 每次内容刷新后检查是否要滚动 function onContentUpdated() { if (isPinnedToBottom) { listEl.scrollTop listEl.scrollHeight; } }40px是阈值给用户最终查看底部留一点点余量不至于手指轻轻一碰就锁死滚动。4. 中文乱码问题的根源与解法4.1 UTF-8 编码边界中文乱码是流式聊天里最常见的毛病。网上很多帖子把原因归结为后端编码问题其实前端处理不当也有可能造成。UTF-8 是一种变长编码。英文字符占 1 字节中文占 3 字节。比如你好两个字在二进制里是 6 个字节。网络传输时这些字节可能被 TCP 或 HTTP 层随意切割。一个中文字符的 3 个字节可能第一个字节在上一个数据块里后两个字节在下一个数据块里。如果你每次把收到的字节直接toString()或者用一个不识别流状态的方式解码这一刀切下去中文字符就碎了屏幕上立刻出现一个。4.2 TextDecoder 的 stream 模式前面代码里我已经加了TextDecoder(utf-8)并传入{ stream: true }这就是解决乱码的钥匙。它的原理是解码器内部维护一个缓存区当检测到末尾的字节构成一个不完整的 UTF-8 序列时不立即解码输出而是缓存起来等后续字节到达。看一个完整的、刻意犯错的对比// 错误示范不用 stream 模式 const decoder new TextDecoder(utf-8); decoder.decode(new Uint8Array([0xE4, 0xBD])); // 你的前两个字节 // 输出 // 正确做法启用 stream 模式 const streamDecoder new TextDecoder(utf-8); streamDecoder.decode(new Uint8Array([0xE4, 0xBD]), { stream: true }); // 输出 (空字符串等待后续字节) streamDecoder.decode(new Uint8Array([0xA0]), { stream: true }); // 输出你同样的字节两种方式的结果天差地别。这是任何一个做 H5 AI 聊天的人都必须牢记的心法。4.3 实测验证步骤假如你的页面里乱码还是出现了我不太建议一开始就翻服务端代码。先把前端这一段排查逻辑理顺。我的做法是在回调函数里临时加上一段调试代码onDelta: (data) { console.log(原始块字符串, data); console.log(Unicode 码点, Array.from(data).map(c c.codePointAt(0).toString(16))); }如果输出里出现fffd这个码点说明解码阶段已经有字符被替换成了。这时候检查的重点就是有没有用stream: true以及有没有对 buffer 做正确的跨分包拼接。如果码点全是正常的中文区段比如4f60对应你才需要考虑是不是后端返回的文本编码根本不是 UTF-8。5. 取消、重试、多轮会话管理5.1 AbortController 中断请求用户在 AI 生成过程中经常会点停止生成按钮。前端必须立刻终止网络请求否则服务端还在消耗算力往客户端发数据。上一段代码里的controller就是为这个准备的。中断逻辑如下let currentController null; function stopGeneration() { if (currentController) { currentController.abort(); } } // 发送时保存 controller async function sendMessage() { currentController new AbortController(); await streamChat({ // ... signal: currentController.signal }); }这里有一个容易忽略的点abort()调用后fetch 的 promise 会抛出一个AbortError异常。如果你的 catch 块没有针对这个错误单独处理界面上就会弹出一个错误 toast。正确做法是在 catch 里判断err.name AbortError然后安静地返回。5.2 超时与断线重连H5 网络环境极为复杂地铁过隧道、电梯切换基站Wi-Fi 信号不好都可能导致 fetch 卡死。这时候需要一个超时机制。我的做法是封装一个带超时控制的包装函数function withTimeout(fetchPromise, timeoutMs 30000) { return Promise.race([ fetchPromise, new Promise((_, reject) { setTimeout(() reject(new Error(请求超时)), timeoutMs); }) ]); }注意这里有一个问题Promise.race中超时胜出并不会自动取消底层 fetch。正确做法是在超时回调里手动调用controller.abort()。我一般写成下面这样function createTimeoutController(timeoutMs) { const controller new AbortController(); const timer setTimeout(() controller.abort(), timeoutMs); return { controller, timer }; } // 使用 const timeoutCtrl createTimeoutController(15000); try { const res await fetch(/api/chat/stream, { signal: timeoutCtrl.signal }); // 继续读取流 } finally { clearTimeout(timeoutCtrl.timer); }超时时间我建议设置在 15~30 秒之间。太短了模型生成长文本时正常停顿也会被误杀太长了用户等待成本太高。如果超时后前端还想自动重试我一般只重试一次因为第二次很可能还是失败连续重试反而会让服务端压力变大。5.3 多轮会话的消息拼接AI 聊天的上下文通常由前端维护。每次发送新消息时要把历史对话 JSON 一并传给后端。流式场景下这个消息列表的管理也有讲究。我在项目中用一个数组保存会话内容const sessionMessages []; function appendMessage(role, content) { if (content) { sessionMessages.push({ role, content }); } } async function sendMessage(message) { // 先把用户消息加入上下文 appendMessage(user, message); const messagesForApi sessionMessages.slice(-10); // 最近10条避免上下文过长 await streamChat({ message: messagesForApi, onDelta: (text) { // 实时更新最后一条 assistant 消息 updateLastAssistantContent(text); }, onDone: () { // 最终确定 assistant 消息内容存入历史 finalizeAssistantMessage(); appendMessage(assistant, getLastAssistantContent()); } }); }注意sessionMessages.slice(-10)这个设定。很多大模型接口对上下文长度有上限比如 16K token。如果所有历史都塞进去早期消息占用的 token 会白白浪费而且模型注意力会被稀释。只保留最近 10 轮是实践下来性价比不错的折中方案。更新的过程中需要实时改变最后一条 assistant 消息的显示内容但不要每接收一个字符就往sessionMessages里 push 一条新记录不然内存和后续 API 的请求体都会爆炸。正确思路是有一个当前生成中的 assistant 消息载体然后动态更新它的 content等流结束后统一固化。6. 常见问题与排查技巧实录6.1 问题速查表我把过去项目里遇到的高频问题整理成一张表方便你按图索骥现象常见原因解决方案中文乱码出现TextDecoder 未开启 stream 模式解码时传入{ stream: true }数据断断续续丢失没有用 buffer 缓存不完整行按 \n 拆分时保留最后一段页面滚动卡顿每收到数据立即操作 DOM引入渲染队列40~60ms 刷新一次iOS 上滚动不流畅缺少-webkit-overflow-scrolling: touch消息列表容器补充该 CSS 属性停止生成不生效请求超时导致的错误被误报catch 中单独判断 AbortError长时间无响应网络切换fetch 卡死使用带 abort 的超时控制Android 低端机卡顿渲染队列过短频繁绘制调大 flushInterval降低 DOM 操作频率请求跨域失败服务端未配置 CORS后端添加Access-Control-Allow-Origin等头6.2 核心排查思路与真机调试技巧真机调试是 H5 开发里最让人头疼的一个环节尤其是 AI 聊天这种流式场景手机上出现的问题电脑浏览器不一定复现得了。我自己习惯的做法是分三步走。第一步在电脑浏览器上用 Network 面板观察有没有持续的网络请求活动。如果数据流在 Network 界面上能看到连续的EventStream条目说明网络层是通的问题大概率出在前端解析层。第二步在手机上用 Safari 或 Chrome 的远程调试工具打开 Console 看有没有报错。重点看TextDecoder相关的警告很多低版本 WebView 对stream属性支持不完整需要降级方案。第三步把原始数据打出来。前面的章节中写过一个调试技巧就是console.log原始 chunk这个信息量最大。它能直接告诉你哪些字符是完整的中文哪些被拆散了。如果原始字节本身就不完整那问题不在前端解析而在服务端的分包策略。关于低版本 WebView 兼容性我还想多说一句。如果你要支持 iOS 12 以下或某些 Android 定制内核ReadableStream不一定可用。一个常见降级方案是后端额外提供轮询接口前端用setInterval定期拉取增量文本。这个方案不够优雅但稳定。如果项目用户基数大、老旧机型多可以考虑做特性检测优先使用现代方案检测失败再降级到轮询。6.3 两个容易被忽略的小细节聊两个细节。一个是onDone和onDelta的执行顺序。真实的流式传输里最后一条数据后面往往紧跟一个空行或者一个[DONE]标记。如果你在while循环读取完donetrue后又手动调用了一次onDone可能导致状态重复设置。我通常的做法是全局用一个finished标志位保证onDone只执行一次。另一个细节是页面切后台再切回来。有些 WebView 在应用切后台时会暂停网络请求导致流式传输中断。此时用户回到页面看到的是一条未说完的话。我的方案是监听页面的visibilitychange事件在页面重新可见时如果发现还在流式加载状态但连接已断开就自动触发一次重试或明确提示用户手动重试。这在移动端体验上有很大帮助因为用户切出去回了个微信消息回来偏偏看到消息停在半截会一头雾水。7. 选型建议与封装思路7.1 三种方案对比总结做一个横向对比方便你在项目选型时快速决策。维度SSE (EventSource)WebSocketfetch ReadableStream通信方向单向服务端到客户端双向全双工标准请求响应内实现流式传请求头不支持只能 GET支持完全自由断线重连原生自带需自己实现心跳重连需自己实现解析成本底层封装较黑盒须自定义业务协议完全可控解析 SS E 协议即可适合场景简单展示、快速Demo强双向交互、需要主动推送生产环境 AI 聊天如果是正式上线一个 AI 聊天产品我个人的建议非常明确直接选 fetch ReadableStream。它把请求侧的控制权完全交给你是只成本收益比最高的方案。WebSocket 不是不行但它在服务端多出的配合和状态维护工作大部分中小前端团队得不偿失。7.2 如何封装一个可复用的流式客户端项目写多了你会发现流式聊天逻辑完全可以封装成一个独立的工具类不绑定任何 UI 框架。我给你看一个简化但能直接用的封装骨架class AIChatClient { constructor({ url, timeout 20000, onDelta, onDone, onError }) { this.url url; this.timeout timeout; this.onDelta onDelta; this.onDone onDone; this.onError onError; this.controller null; } async send(messages) { const { controller, timer } createTimeoutController(this.timeout); this.controller controller; try { const response await fetch(this.url, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ messages }), signal: controller.signal }); if (!response.ok) { throw new Error(HTTP ${response.status}); } const reader response.body.getReader(); const decoder new TextDecoder(utf-8); let buffer ; let finished false; while (true) { const { done, value } await reader.read(); if (done) break; buffer decoder.decode(value, { stream: true }); const lines buffer.split(\n); buffer lines.pop(); for (const line of lines) { const parsed parseSSELine(line); if (!parsed) continue; if (parsed [DONE]) { finished true; break; } this.onDelta this.onDelta(parsed); } if (finished) break; } if (!finished buffer) { // 处理最后残留的未分行情理 const parsed parseSSELine(buffer.trim()); if (parsed parsed ! [DONE] parsed ! [END]) { this.onDelta this.onDelta(parsed); } } this.onDone this.onDone(); } catch (err) { if (err.name ! AbortError) { this.onError this.onError(err); } } finally { clearTimeout(timer); this.controller null; } } stop() { this.controller this.controller.abort(); } }用这个类在任意页面里只需要三行代码就能跑起来了const client new AIChatClient({ url: /api/chat/stream, onDelta: (text) renderStreamingText(text), onDone: () setStreaming(false), onError: (err) showErrorTip(err.message) }); client.send([{ role: user, content: 请写一首七言绝句 }]);封装的好处是无论你用的是 React、Vue 还是原生小程序只要把onDelta回调里的 UI 更新逻辑换掉整个数据层可以直接复用。8. 写在最后的实战体会做 AI 聊天界面前端说到底拼的是细节处理能力。很多人觉得流式数据就是后端返回一段我拼一段实际上从协议选择、编码解码、缓冲拼接、渲染节流到异常处理每一环都有坑。我自己踩过最深刻的一次教训是在 Android 低端机上用每 20ms 刷新一次 DOM结果导致页面完全卡死用户输入框都点不动。后来改成requestAnimationFrame加叠加队列才彻底解决问题。现在回想起来所有性能问题在引入渲染队列这个思路之后几乎都变得可控了。另外还有一个体会如果你打算把 AI 聊天功能长期维护下去尽早做一套纯前端、与框架无关的流式客户端封装非常重要。因为模型服务商时不时会调整返回格式有了独立的解析层你只需要改一个函数就能适配。我在自己项目里的做法是把parseSSELine、createTimeoutController、StreamingRenderer这三个模块单独抽出去写成一个独立的 utils 文件并在代码注释里写清楚每一种返回格式的处理逻辑。后续加新功能时连回忆成本都省了。如果这篇文章里的经验能让你少走几次弯路那就值了。毕竟 H5 里的 AI 流式聊天看着简单写起来全是细节。