前端使用 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 随时中断生成"]
  1. 只支持 GET 请求,无法携带长上下文:
    大模型每次生成都需要携带包含多轮历史记录的 messages 数组、系统提示词(system)、工具调用(tools)及控制参数(temperature)。这些庞大的 JSON 载荷动辄数千甚至数万字符,GET 请求的 URL 长度限制(通常为 2KB~8KB)根本无法承受;
  2. 无法携带自定义 HTTP Headers(鉴权隐患):
    EventSource 不允许开发者设置请求头。如果要传递鉴权凭据,开发者只能被迫将 Token 拼接到 URL Query 参数中(如 ?token=xxx),这会导致敏感凭据被反向代理(如 Nginx)、网关日志以及浏览器历史记录明文记录,存在严重的安全隐患;
  3. 缺乏精细的生命周期与中断控制:
    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
2
3
4
5
// ❌ 冗余:response.body 本身已经是 ReadableStream,无需再 new 一个包裹
const reader = response.body.getReader();
return new ReadableStream({
start(controller) { ... }
});

实际上,直接从 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
2
// ❌ 错误:如果汉字跨越两个 Chunk,末尾字节会直接解码为乱码占位符 
const text = textDecoder.decode(value);

正确解法:必须给解码器传入 { stream: true },告诉解码器保持内部未决状态:

1
2
// ✅ 正确:流式解码模式,保留未完成的字节序列与下一个分块拼接
const text = textDecoder.decode(value, { stream: true });

3. SSE 消息的粘包与半包(直接 JSON.parse 崩溃)

根据 W3C SSE 规范,SSE 协议是以换行为边界的文本协议,每条事件之间使用两个连续换行符 \n\n 结尾,格式如下:

1
2
3
event: message\n
data: {"content": "你"}\n\n
data: {"content": "好"}\n\n

网络分块传输不是“一次网络分块 = 一条完整的 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
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
/**
* 基于原生 Fetch 实现的 SSE 流式客户端
* @param {string} url 请求地址
* @param {object} options 配置选项
* @param {string} options.method 请求方法,默认为 POST
* @param {object} options.headers 请求头
* @param {any} options.body 请求体载荷
* @param {AbortSignal} options.signal 用于中断请求的 AbortSignal
* @param {function} options.onMessage 接收到有效数据块的回调 (dataStr, rawEvent) => void
* @param {function} options.onError 异常回调 (error) => void
* @param {function} options.onClose 连接结束回调 () => void
*/
async function fetchSSE(url, options = {}) {
const {
method = 'POST',
headers = {},
body = null,
signal,
onMessage = () => {},
onError = () => {},
onClose = () => {}
} = options;

try {
const response = await fetch(url, {
method,
headers: {
'Accept': 'text/event-stream',
'Content-Type': 'application/json',
...headers
},
body: body ? JSON.stringify(body) : null,
signal
});

if (!response.ok) {
throw new Error(`HTTP 请求失败,状态码: ${response.status} (${response.statusText})`);
}

if (!response.body) {
throw new Error('当前运行环境不支持 ReadableStream!');
}

const reader = response.body.getReader();
// 关键点 1: 初始化解码器
const decoder = new TextDecoder('utf-8');
// 关键点 2: 维护行级消息缓冲区
let buffer = '';

while (true) {
const { done, value } = await reader.read();

if (done) {
// 读取流结束,刷新解码器剩余内容
buffer += decoder.decode();
break;
}

// 关键点 3: stream: true 模式保留多字节字符的断字节
buffer += decoder.decode(value, { stream: true });

// 关键点 4: 按行切分处理半包与粘包
const lines = buffer.split('\n');
// 最后一行可能未接收完整,保留在 buffer 中继续等待下一个 chunk
buffer = lines.pop() || '';

for (const line of lines) {
const trimmedLine = line.trim();
// 忽略心跳注释行 (以冒号开头) 或空行
if (!trimmedLine || trimmedLine.startsWith(':')) {
continue;
}

// 匹配 SSE 的 data 字段
if (trimmedLine.startsWith('data:')) {
const dataContent = trimmedLine.slice(5).trim();

// 约定俗成的大模型结束标识符
if (dataContent === '[DONE]') {
onClose();
return;
}

onMessage(dataContent);
}
}
}

onClose();
} catch (error) {
if (error.name === 'AbortError') {
console.log('[SSE] 请求已被前端主动中断。');
} else {
onError(error);
}
}
}

使用范例与中止控制

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
// 1. 创建中断控制器
const abortController = new AbortController();

// 2. 发起大模型对话请求
fetchSSE('https://api.your-ai-service.com/v1/chat/completions', {
method: 'POST',
headers: {
'Authorization': 'Bearer sk-your-token-here'
},
body: {
model: 'gpt-4o-mini',
messages: [
{ role: 'user', content: '请用通俗的语言解释什么是量子纠缠?' }
]
},
signal: abortController.signal,
onMessage(dataStr) {
try {
const json = JSON.parse(dataStr);
const textChunk = json.choices?.[0]?.delta?.content || '';
// 实时追加到 UI 界面上,呈现打字机效果
document.getElementById('ai-output').innerText += textChunk;
} catch {
document.getElementById('ai-output').innerText += dataStr;
}
},
onError(err) {
console.error('SSE 通信发生异常:', err);
},
onClose() {
console.log('大模型回复完毕!');
}
});

// 3. 用户点击“停止生成”按钮时调用:
document.getElementById('stop-btn').addEventListener('click', () => {
abortController.abort();
});

五、方案二:工业级最佳实践 —— @microsoft/fetch-event-source

在生产级工程中,除了手动写状态机切分分包,微软官方为解决 EventSource 限制开源的包 @microsoft/fetch-event-source 是目前业界使用最广泛的库。

1. 为什么选择微软官方库?

  • 天然支持全部 Fetch 选项:轻松支持 POST、自定义 Headers、Body 等;
  • 智能重连退避机制:连接异常断开时,自动根据服务端返回的 retry: [ms] 字段或指数退避策略重试,并自动带上 Last-Event-ID 恢复状态;
  • 页面失焦自动保持:原生 EventSource 在浏览器标签页切后台时可能会降低拉取频率或断开,该库使用原生 Fetch 维持稳定的连接。

2. 安装与使用

1
npm install @microsoft/fetch-event-source

在 React / Vue / 原生项目中使用:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
import { fetchEventSource } from '@microsoft/fetch-event-source';

const ctrl = new AbortController();

await fetchEventSource('/api/v1/chat', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${localStorage.getItem('token')}`,
},
body: JSON.stringify({
prompt: '用 Python 实现一个快速排序算法',
}),
signal: ctrl.signal,

// 校验响应状态
async onopen(response) {
if (response.ok && response.headers.get('content-type')?.includes('text/event-stream')) {
return; // 正常建立连接
}
throw new Error(`服务器未响应 SSE 流格式,状态码: ${response.status}`);
},

// 接收到完整的事件消息
onmessage(msg) {
if (msg.event === 'FatalError') {
throw new Error(msg.data);
}
// msg.data 即为已解析好的单条消息字符串
console.log('接收到片段:', msg.data);
},

// 连接正常关闭
onclose() {
console.log('服务端推送完毕,连接安全关闭');
},

// 错误处理与重试策略控制
onerror(err) {
console.error('发生连接错误:', err);
// 若返回一个重试毫秒数则会继续重连,若重新抛出异常则停止重试
throw err;
}
});

六、配套服务端验证:15 行 Node.js/Express 模拟服务

为了方便前端开发者在本地直接联调验证流式打字机效果,无需购买任何 API Key,可直接使用以下极简 Express 脚本搭建模拟服务端:

新建 server.mjs:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
import express from 'express';
import cors from 'cors';

const app = express();
app.use(cors());
app.use(express.json());

app.post('/api/chat', (req, res) => {
// 1. 核心关键:设置 SSE 标准响应头
res.writeHead(200, {
'Content-Type': 'text/event-stream',
'Cache-Control': 'no-cache',
'Connection': 'keep-alive',
});

const prompt = req.body?.prompt || '默认提示词';
const replyText = `【AI思考完成】针对你的问题:“${prompt}”,这是一个使用 Fetch + SSE 实现的打字机流式响应示例,支持多行文本与 Emoji ✨。`;
let index = 0;

// 2. 模拟大模型按 Token 逐字推送
const timer = setInterval(() => {
if (index < replyText.length) {
const char = replyText[index++];
// 按照 SSE 规范格式: data: <内容>\n\n
res.write(`data: ${JSON.stringify({ char })}\n\n`);
} else {
res.write('data: [DONE]\n\n');
clearInterval(timer);
res.end();
}
}, 60);

// 3. 客户端主动中断时清理定时器
req.on('close', () => {
clearInterval(timer);
console.log('客户端中断连接,停止发送。');
});
});

app.listen(3000, () => console.log('SSE 模拟服务端已启动: http://localhost:3000'));

运行服务:

1
node server.mjs

前端将 fetchSSE 请求地址指向 http://localhost:3000/api/chat,即可立即在控制台或界面上看到平滑流畅的打字机输出!


七、技术选型横向对比:SSE vs WebSocket

对比维度原生 EventSourceFetch + ReadableStreamWebSocket
通信方向仅单向(服务端 $\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。


八、参考资料与规范扩展

  1. 📖 WHATWG Streams API 标准规范 — ReadableStream 与流读取器标准
  2. 📖 MDN: Server-sent events 官方指南 — SSE 基础规范与协议格式
  3. 📖 MDN: Using ReadableStream with Fetch — 使用 Fetch 读取流式响应最佳实践
  4. 🚀 GitHub: @microsoft/fetch-event-source — 微软官方出品的高可用 EventSource 客户端
  5. 📖 OpenAI API Reference: Streaming Responses — 现代大模型 SSE 流式输出规范

前端使用 Fetch 实现 SSE 流式通信
https://bubao.github.io/posts/3e0444b9.html
作者
一念
发布于
2023年5月19日
许可协议