前端使用 Fetch 实现 SSE 流式通信
随着 ChatGPT、Claude、DeepSeek 等大语言模型(LLM)的普及,打字机式逐字流式输出已经成为现代 AI 应用的标准交互范式。在大模型与前端的通信协议中,SSE(Server-Sent Events,服务端推送事件) 凭借轻量、单向契合、天然复用 HTTP/2 等特性成为了事实上的工业标准。
然而,浏览器原生的 EventSource API 存在致命限制:仅支持 GET 请求,无法传递复杂 JSON Body,且不支持携带自定义 Header(如 Authorization Token)。
本文系统拆解如何使用现代浏览器的 fetch 与 ReadableStream 完整实现支持 POST 与自定义请求头的 SSE 客户端,剖析流式分包、UTF-8 字符截断乱码、断网重连与 Abort 中断等核心避坑点,并给出生产级原生封装方案与微软官方开源库实践。
一、为什么原生 EventSource 无法满足大模型需求?
浏览器早在 HTML5 时代就提供了原生的 EventSource 接口用于接收 SSE 数据流,但在面对大模型对话场景时,它暴露了三个无法绕开的硬伤:
flowchart LR
A["大模型对话请求
(复杂上下文 / 鉴权)"] --> B{"通信技术选型"}
B -->|"❌ 浏览器原生 EventSource"| C["限制1: 仅支持 GET (URL 长度受限)
限制2: 无法自定义 Header (Token 易泄露)
限制3: 无法直接中止 Abort 生成"]
B -->|"✅ Fetch + ReadableStream"| D["支持 POST 复杂上下文 Body
支持 Authorization 等自定义 Header
结合 AbortController 随时中断生成"]
- 只支持 GET 请求,无法携带长上下文:
大模型每次生成都需要携带包含多轮历史记录的messages数组、系统提示词(system)、工具调用(tools)及控制参数(temperature)。这些庞大的 JSON 载荷动辄数千甚至数万字符,GET 请求的 URL 长度限制(通常为 2KB~8KB)根本无法承受; - 无法携带自定义 HTTP Headers(鉴权隐患):
EventSource不允许开发者设置请求头。如果要传递鉴权凭据,开发者只能被迫将 Token 拼接到 URL Query 参数中(如?token=xxx),这会导致敏感凭据被反向代理(如 Nginx)、网关日志以及浏览器历史记录明文记录,存在严重的安全隐患; - 缺乏精细的生命周期与中断控制:
AI 对话中高频出现的“停止生成(Stop Generating)”功能,原生EventSource只能通过粗暴的.close()掐断,无法与现代 Promise 异步任务或AbortController形成联动。
因此,利用原生 fetch 获取 response.body(ReadableStream)并在前端自行解析 SSE 协议,是现代 AI Web 应用的唯一正确选择。
二、Fetch 处理 SSE 流的底层流水线
浏览器通过 fetch 请求一个 Content-Type: text/event-stream 的接口时,连接并不会立即关闭,服务端会以分块(Chunk)形式源源不断推送二进制数据:
flowchart TD
A["前端发起 fetch(POST, { body, headers })"] --> B["获取 Response: text/event-stream"]
B --> C["获取流读取器: response.body.getReader()"]
C --> D["循环读取分块: reader.read()"]
D --> E["增量解码: TextDecoder('utf-8', { stream: true })"]
E --> F["缓冲区切分: 处理粘包与半包 (按 \\n\\n 分隔)"]
F --> G["解析行协议: data: {...}"]
G --> H["触发业务回调: onMessage(data)"]
D -.->|"用户点击'停止'或服务端结束"| I["AbortController.abort() / 关闭 Reader"]
三、初学者常踩的三大硬伤(踩坑复盘)
很多开发者初次尝试用 fetch 读取 SSE 流时,往往会写出脆弱的演示代码,在生产环境中频繁遇到以下问题:
1. 冗余嵌套流(画蛇添足)
部分早期教程会写出类似下面的代码:
1 | |
实际上,直接从 response.body.getReader() 循环 read(),或者使用现代原生的 for await (const chunk of response.body) 语法即可,二次封装纯属多余。
2. UTF-8 中文字符断包与乱码(致命)
UTF-8 编码下一个汉字通常占用 3 个字节。网络底层的 TCP 分包是按字节流切片的,极有可能一个汉字的第 1、2 个字节落在前一个 Chunk,而第 3 个字节落在后一个 Chunk。
如果像下面这样直接对每个 value 单独 decode():
1 | |
正确解法:必须给解码器传入 { stream: true },告诉解码器保持内部未决状态:
1 | |
3. SSE 消息的粘包与半包(直接 JSON.parse 崩溃)
根据 W3C SSE 规范,SSE 协议是以换行为边界的文本协议,每条事件之间使用两个连续换行符 \n\n 结尾,格式如下:
1 | |
网络分块传输不是“一次网络分块 = 一条完整的 SSE 消息”:
- 粘包:一个 Chunk 里面可能一口气塞了 3 条
data:消息; - 半包:一个几千字符的复杂 JSON 数据,可能前半截在当前 Chunk,后半截还在路上。
如果不维护一个文本缓冲区(Buffer)按行解析,直接盲目执行 JSON.parse(chunk.replace('data: ', '')),终端将频繁抛出 SyntaxError: Unexpected end of JSON input 异常!
四、方案一:纯原生 Fetch + SSE 流式解析器(零依赖生产级实现)
下面是一个纯原生 JavaScript 实现的高可用 SSE 客户端函数,支持 POST 请求体、自定义 Header、完整的行级协议解析、乱码防护以及 AbortController 中断:
1 | |
使用范例与中止控制
1 | |
五、方案二:工业级最佳实践 —— @microsoft/fetch-event-source
在生产级工程中,除了手动写状态机切分分包,微软官方为解决 EventSource 限制开源的包 @microsoft/fetch-event-source 是目前业界使用最广泛的库。
1. 为什么选择微软官方库?
- 天然支持全部 Fetch 选项:轻松支持
POST、自定义 Headers、Body 等; - 智能重连退避机制:连接异常断开时,自动根据服务端返回的
retry: [ms]字段或指数退避策略重试,并自动带上Last-Event-ID恢复状态; - 页面失焦自动保持:原生
EventSource在浏览器标签页切后台时可能会降低拉取频率或断开,该库使用原生 Fetch 维持稳定的连接。
2. 安装与使用
1 | |
在 React / Vue / 原生项目中使用:
1 | |
六、配套服务端验证:15 行 Node.js/Express 模拟服务
为了方便前端开发者在本地直接联调验证流式打字机效果,无需购买任何 API Key,可直接使用以下极简 Express 脚本搭建模拟服务端:
新建 server.mjs:
1 | |
运行服务:
1 | |
前端将 fetchSSE 请求地址指向 http://localhost:3000/api/chat,即可立即在控制台或界面上看到平滑流畅的打字机输出!
七、技术选型横向对比:SSE vs WebSocket
| 对比维度 | 原生 EventSource | Fetch + ReadableStream | WebSocket |
|---|---|---|---|
| 通信方向 | 仅单向(服务端 $\to$ 客户端) | 仅单向(服务端 $\to$ 客户端) | 全双工(双向即时互传) |
| HTTP 请求方法 | 仅支持 GET | 任意方法(GET/POST/PUT) | 基于 TCP 握手升级(ws://) |
| 自定义 Header | ❌ 不支持 | ✅ 完全支持 | ❌ 浏览器端仅支持协议子协议 |
| 传输协议承载 | HTTP/1.1 或 HTTP/2 多路复用 | HTTP/1.1 或 HTTP/2 多路复用 | 独立的 WS 协议,需反代额外升级配置 |
| 防火墙与网关穿透 | 原生友好(普通 HTTP 流量) | 原生友好(普通 HTTP 流量) | 偶尔会被公司代理或网关拦截 |
| 典型适用场景 | 简单股票看板、系统通知 | 大语言模型(LLM)对话输出 | 多人在线协同文档、云游戏、即时聊天室 |
💡 架构选型建议:
对于绝大多数 AI 聊天、文生图进度追踪、报告生成场景,客户端只需要在建立连接时发一次长文本 Prompt,随后全是服务端单向吐字。这种场景采用 SSE(Fetch 实现) 是性价比最高、对现有微服务网关改造最小的最佳选择。只有在需要频繁双向低延迟交互(如语音实时对讲、画布协同)时,才需要考虑引入重量级的 WebSocket。
八、参考资料与规范扩展
- 📖 WHATWG Streams API 标准规范 —
ReadableStream与流读取器标准 - 📖 MDN: Server-sent events 官方指南 — SSE 基础规范与协议格式
- 📖 MDN: Using ReadableStream with Fetch — 使用 Fetch 读取流式响应最佳实践
- 🚀 GitHub: @microsoft/fetch-event-source — 微软官方出品的高可用 EventSource 客户端
- 📖 OpenAI API Reference: Streaming Responses — 现代大模型 SSE 流式输出规范
