企业官网建设流程全解析

流式对话 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