从 0 实现 ChatGPT 风格的流式对话 UI

流式对话 UI 表面上是「后端推 chunk、前端拼进 state」，实际上线后通常会碰到这几类问题：Markdown 边输出边闪、每个 chunk 触发重渲染导致掉帧、自动滚动打断用户翻历史、点了停止但 loading 没收干净。下面按实现顺序拆开讲。

传输层：SSE + fetch

写 UI 之前，先搞清楚数据怎么从服务端流到浏览器。常见三种：

LLM 对话是单向的：问一次，答一长串，生成过程中客户端不需要往回发数据。SSE 语义匹配，走标准 HTTP，鉴权、网关、CDN 都能复用。OpenAI、Claude 官方接口也是这个路子。

格式简单：Content-Type: text/event-stream，每条事件 data: {...}\n\n。

注意：原生“EventSource”只支持 GET，不能自定义请求头。调 LLM 要 POST messages 并带“Authorization”，所以实际项目里几乎都用“fetch”读 body，自己按 SSE 格式解析，而不是“EventSource”。

“streamChat()”：async generator 封装

response.body.getReader() 逐块读，按 \n\n 切事件，从 data: 提取 delta，yield 出去：

// streamChat.ts
export interface StreamChatOptions { 
 messages: { role: 'user' | 'assistant' | 'system'; content: string }[] 
 signal?: AbortSignal // 用于中断} 
 
export async function* streamChat({ messages, signal }: StreamChatOptions) { 
 const res = await fetch('/api/chat', { 
 method: 'POST', 
 headers: { 'Content-Type': 'application/json' }, 
 body: JSON.stringify({ messages, stream: true }), 
 signal, 
 })  
 
 if (!res.ok || !res.body) { 
 throw new Error(`请求失败: ${res.status}`) 
 }  
 
 const reader = res.body.getReader() 
 const decoder = new TextDecoder('utf-8') 
 let buffer = ''  
 
 while (true) { 
 const { done, value } = await reader.read() 
 if (done) break  
// chunk 可能在任意字节处被切断，必须 buffer 拼接 
 buffer += decoder.decode(value, { stream: true })  
// SSE 以 \n\n 分隔每条事件 
 const lines = buffer.split('\n\n') 
 buffer = lines.pop() ?? '' // 最后一段可能不完整，留到下次  
 
 for (const block of lines) { 
 const line = block.trim() 
 if (!line.startsWith('data:')) continue  
 
 const data = line.slice(5).trim() 
 if (data === '[DONE]') return // OpenAI 风格的结束标记  
 
 try { 
 const json = JSON.parse(data) 
 const delta = json.choices?.[0]?.delta?.content 
 if (delta) yield delta as string 
 } catch { 
 // 半条 JSON，忽略；正常不会走到这，因为按 \n\n 切过了 
 } 
 } 
 }
}

消费：

for await (const chunk of streamChat({ messages, signal })) { 
 console.log(chunk)
}

解析层最容易踩坑的地方：“reader.read()” 返回的字节块不保证落在字符边界，也不保证落在 SSE 事件边界。汉字 UTF-8 占三个字节，可能被切成两半；一条 “data:”也可能拦腰截断。必须同时做两件事：

1. decoder.decode(value, { stream: true }) —— 让 decoder 缓存不完整的多字节字符。

2. 用 buffer 累积，按 \n\n 切分，末尾不完整的一段留到下一轮。

缺任何一个，中文乱码或 JSON.parse 失败会随机出现，慢网下更容易复现。

打字机：收流和显示要解耦

流接好后，常见写法是每个 chunk 直接追加到 state：

for await (const chunk of streamChat({ messages })) { 
 setText(prev => prev + chunk)
}

问题在于 LLM 吐 token 节奏不均匀——有时长时间无输出，有时一口气推半段。直接拼接会出现「顿一下、蹦一大段」，和 ChatGPT 的匀速感差很远；chunk 密集时高频 setState 还会拖慢 reconcile，Markdown 重渲染时更明显。

逐 token 显示（来一个显示一个）实现最简单，但粒度不均，视觉上忽快忽慢。更稳的做法是把接收和显示拆开：网络层往缓冲区写，显示层用 “requestAnimationFrame”匀速吐字。

// typewriter.ts —— 框架无关，React/Vue 共用
export function createTypewriter(onUpdate: (text: string) => void) { 
 let displayed = '' 
 let pending = '' 
 let rafId: number | null = null  


// 手感旋钮：中文 2~3，英文 4~6 
 const CHARS_PER_FRAME = 2  
 
 function tick() { 
 if (pending.length > 0) { 
 const take = Math.min(CHARS_PER_FRAME, pending.length) 
 displayed += pending.slice(0, take) 
 pending = pending.slice(take) 
 onUpdate(displayed) 
 } 
 if (pending.length > 0) { 
 rafId = requestAnimationFrame(tick) 
 } else { 
 rafId = null 
 } 
 }  
 
 return { 
 push(chunk: string) { 
 pending += chunk 
 if (rafId === null) 
 rafId = requestAnimationFrame(tick) 
 }, 
 
// 流结束时调用，避免网络已结束 UI 还在逐字蹦 
 flush() { 
 displayed += pending 
 pending = '' onUpdate(displayed) 
 if (rafId !== null) { 
 cancelAnimationFrame(rafId) 
 rafId = null 
 } 
 }, 
 get text() { 
 return displayed 
 }, 
 }
}

React / Vue 接入

React：

import { useState, useRef, useCallback } from 'react'
import { streamChat } from './streamChat'
import { createTypewriter } from './typewriter' 


export function useStreamingChat() { 
 const [text, setText] = useState('') 
 const [loading, setLoading] = useState(false) 
 const abortRef = useRef<AbortController | null>(null)  
 
 const send = useCallback(async (messages) => { 
 setText('') 
 setLoading(true) 
 const controller = new AbortController() 
 abortRef.current = controller 
 const typer = createTypewriter(setText)  
 
 try { 
 for await (const chunk of streamChat({ messages, signal: controller.signal })) { 
 typer.push(chunk) 
 } 
 typer.flush() 
 } catch (err) { 
 if ((err as Error).name !== 'AbortError') { 
 setText(t => t + '\n\n⚠️ 出错了，请重试') 
 } 
 } finally { 
 setLoading(false) 
 abortRef.current = null 
 } 
 }, [])  
 
 const stop = useCallback(() => abortRef.current?.abort(), [])  
 
 return { text, loading, send, stop }
}

Vue 只是把 setText 换成 text.value =：

// useStreamingChat.ts
import { ref } from 'vue'
import { streamChat } from './streamChat'
import { createTypewriter } from './typewriter' 


export function useStreamingChat() { 
 const text = ref('') 
 const loading = ref(false) 
 let controller: AbortController | null = null  
 
 async function send(messages) { 
 text.value = '' 
 loading.value = true 
 controller = new AbortController() 
 const typer = createTypewriter(t => (text.value = t))  
 
 try { 
 for await (const chunk of streamChat({ messages, signal: controller.signal })) { 
 typer.push(chunk) 
 } 
 typer.flush() 
 } catch (err) { 
 if ((err as Error).name !== 'AbortError') { 
 text.value += '\n\n⚠️ 出错了，请重试' 
 } 
 } finally { 
 loading.value = false 
 controller = null 
 } 
 }  
 
 function stop() { 
 controller?.abort() 
 }  
 return { text, loading, send, stop }
}

typewriter.ts 与框架无关，React、Vue 共用同一份。

流式 Markdown：未闭合语法导致闪烁

回答里一旦带 Markdown（代码块、列表、表格），边输出边解析就会出问题。比如模型正在输出：

这是一段代码：
```js
const a = 1

结尾的“```”还没到时，解析器面对的是未闭合的代码块。不同库行为不一致：有的把后续内容全当 code，有的当普通文本——每来一个 chunk，DOM 结构就变一轮，屏幕闪烁。列表（“-”）、表格（“|”）在半截状态同样麻烦。

两种方案

**方案 A：“react-markdown”+ 节流 + 补全语法。**接入成本最低，适合大多数项目。Markdown 不必每个 rAF 帧都 parse，节流约 60ms；渲染前对文本做闭合补全。

import ReactMarkdown from 'react-markdown'
import { useMemo } from 'react' 


// text 先 throttle（useThrottle / lodash.throttle）
function MarkdownMessage({ text }: { text: string }) { 
 const safe = useMemo(() => completeUnclosed(text), [text]) 
 return <ReactMarkdown>{safe}</ReactMarkdown>
}

方案 B：增量解析（如“streaming-markdown”）或只 parse 变化尾部的自研方案。长代码块场景 CPU 占用更低，但接入成本高，对话量特别大、流畅度要求极高时再考虑。

“completeUnclosed”

渲染前检查围栏和行内反引号，奇数个就临时补闭合符：

export function completeUnclosed(text: string): string { 
 let result = text  
 
 const fenceCount = (result.match(/```/g) || []).length 
 if (fenceCount % 2 === 1) { 
 result += '\n```' 
 }  
 
 const inlineTicks = (result.replace(/```/g, '').match(/`/g) || []).length 
 if (inlineTicks % 2 === 1) { 
 result += '`' 
 }  
 
 return result
}

代码块输出到一半时，解析器看到的是合法闭合块，布局稳定；真正的“```”到达后，临时补的全会被正常替换，用户无感知。

代码高亮：Shiki vs Prism

Shiki 质量高，但是整块 re-highlight。流式过程中每帧对增长中的代码块跑 Shiki，主线程开销很大。更合理的策略：流式期间用纯文本或轻量样式，块闭合后再 Shiki 一次性高亮。Prism 更轻，适合需要实时高亮的场景，画质略逊于 Shiki。

交互细节

中断：“AbortController”

hook 里传入 signal，abort() 后 fetch 抛 AbortError，应静默处理，不当成业务错误。finally 里复位 loading、清除 controller。已生成内容保留，允许继续追问。

function StopButton({ loading, onStop }) { 
 if (!loading) 
 return null return <button onClick={onStop}>■ 停止生成</button>
}

跟随滚动

text 一变就 scrollTop = scrollHeight，用户往上翻历史时会被新 chunk 拽回底部。改法：维护 stick 标志，只有用户距底部 40px 以内才自动跟随；主动上滑则停，滑回底部再恢复。

function useAutoScroll(deps: unknown[]) { 
 const ref = useRef<HTMLDivElement>(null) 
 const stick = useRef(true)  
 
 function onScroll() { 
 const el = ref.current 
 if (!el) return 
 const distance = el.scrollHeight - el.scrollTop - el.clientHeight 
 stick.current = distance < 40 
 }  
 
 useEffect(() => { 
 const el = ref.current 
 if (el && stick.current) { 
 el.scrollTop = el.scrollHeight 
 } 
 }, deps)  
 
 return { ref, onScroll }
}

ref、onScroll 绑到滚动容器，deps 传 [text]。

超时、重试、空响应

- 超时：“AbortSignal.timeout(60_000)”或定时器 abort，避免一直停在「思考中」。

- 重试：网络瞬断可对整次请求退避重试。LLM 流式没有断点续传，重试等于重发请求。

- 空响应：流正常结束但“text”为空，显示「未生成内容，请重试」。

async function withTimeout<T>(p: Promise<T>, ms: number, onTimeout: () => void) { 
 const timer = setTimeout(onTimeout, ms) 
 try {
 return await p 
 } finally { 
 clearTimeout(timer) 
 }
}

Loading 三态

- 首个 chunk 未到：骨架或跳动省略号。

- 正在吐字：光标 ▋，发送按钮换成停止。

- 出错：气泡内错误信息 + 重试。

{loading && text === '' && <ThinkingDots />}
{text && <MarkdownMessage text={text} />}
{loading && text && <span className=”cursor”>▋</span>}

性能与边界

虚拟列表不必过早引入。聊天消息高度不固定（代码块、图片、表格），高度测量成本高。消息数到几百条、Performance 明显吃紧时再考虑 react - window / @tanstack/virtual / vue - virtual - scroller。

几个低成本优化：

- 消息 key 用稳定 id，不用数组下标。

- 历史消息 React.memo / v-memo，只让正在生成的那条高频更新。

- Markdown parse + 高亮配合 ~60ms 节流，与吐字引擎对齐。

移动端：键盘弹起时监听 visualViewport.resize 调整底部 padding；textarea 限高内部滚动。

function autoGrow(el: HTMLTextAreaElement, maxPx = 160) { 
 el.style.height = 'auto' 
 el.style.height = Math.min(el.scrollHeight, maxPx) + 'px'
}

小结

流式 UI 的难点不在「接住流」——fetch + getReader 几十行能搞定。难在边流边渲染：token 节奏与网络解耦、Markdown 半截语法补全、重型高亮延后、滚动让位给用户操作、停止与错误状态区分清楚。排查问题时，优先看 buffer 解码和 Markdown 闭合这两处。

项目地址：

https://github\.com/Mr\-liu6/streaming\-chat