logo

如何实现SSE实时传输数据?工程实践完整教程

作者:搬砖的石头2026.11.17 03:22浏览量:0

简介:SSE(Server-Sent Events)的实现核心只有三步:服务端把响应头设为 `Content-Type: text/event-stream` 并保持连接不关闭,按 `data:` / `event:` / `id:` 的文本格式持续写入数据,客户端用 `EventSource` 对象接收。相比 WebSocket,它基于标准 HTTP、天然支持断线自动重连,是大模型流式输出、日志推送、任务进度等单向推送场景的首选。本文给出可直接落地的服务端与客户端代码、协议细节与生产环境踩坑清单。

一、SSE 的协议本质:一个”不结束”的 HTTP 响应

SSE 不是新协议,它复用了 HTTP/1.1 的分块传输能力。客户端创建一个 EventSource,浏览器自动发起一个持久的 GET 请求;服务端收到后不调用 res.end(),而是把响应体保持打开状态,持续往里写数据。

一次完整的事件流大致长这样:

  1. id: 1001
  2. event: message
  3. data: {"text":"你好"}
  4. : 这是注释行,用于心跳保活
  5. data: 第一行内容
  6. data: 第二行内容

几个容易写错的细节:

字段 作用 注意事项
data 事件正文 多行 data 会被拼接为一条数据,行间用 \n 连接
event 事件类型 默认 message,客户端需 addEventListener 监听自定义类型
id 事件 ID 浏览器会记录,重连时通过 Last-Event-ID 请求头带回
retry 重连间隔(毫秒) 覆盖浏览器默认的 3 秒重连策略
: 开头 注释行 常被用作心跳,客户端会静默忽略

必须以两个换行符 \n\n 结束一个事件 ,这是最常见的”数据收不到”原因。

二、服务端实现

Node.js / Express

  1. const express = require('express');
  2. const app = express();
  3. app.get('/events', (req, res) => {
  4. res.set({
  5. 'Content-Type': 'text/event-stream; charset=utf-8',
  6. 'Cache-Control': 'no-cache, no-transform',
  7. 'Connection': 'keep-alive',
  8. 'X-Accel-Buffering': 'no' // 关闭 Nginx 缓冲,关键
  9. });
  10. res.flushHeaders(); // 立刻把头发出去
  11. let id = Number(req.headers['last-event-id'] || 0);
  12. const send = (event, data) => {
  13. res.write(`id: ${++id}\n`);
  14. if (event) res.write(`event: ${event}\n`);
  15. res.write(`data: ${JSON.stringify(data)}\n\n`);
  16. };
  17. // 心跳:防止中间代理因空闲超时断开连接
  18. const heartbeat = setInterval(() => res.write(': ping\n\n'), 15000);
  19. send('connected', { time: Date.now() });
  20. const timer = setInterval(() => send('tick', { count: n++ }), 1000);
  21. // 必须清理,否则内存与定时器泄漏
  22. req.on('close', () => {
  23. clearInterval(heartbeat);
  24. clearInterval(timer);
  25. });
  26. });
  27. app.listen(3000);

Python / FastAPI

  1. import asyncio, json
  2. from fastapi import FastAPI
  3. from fastapi.responses import StreamingResponse
  4. app = FastAPI()
  5. async def event_stream():
  6. try:
  7. for i in range(100):
  8. yield f"data: {json.dumps({'index': i})}\n\n"
  9. await asyncio.sleep(1)
  10. except asyncio.CancelledError:
  11. return # 客户端断开时生成器被取消
  12. @app.get("/events")
  13. async def sse():
  14. return StreamingResponse(
  15. event_stream(),
  16. media_type="text/event-stream",
  17. headers={
  18. "Cache-Control": "no-cache",
  19. "X-Accel-Buffering": "no",
  20. "Connection": "keep-alive",
  21. },
  22. )

三、客户端实现

  1. const es = new EventSource('/events?token=xxx');
  2. es.addEventListener('connected', (e) => {
  3. console.log('已连接', JSON.parse(e.data));
  4. });
  5. es.onmessage = (e) => console.log('默认消息', e.data);
  6. es.onerror = (err) => {
  7. // 浏览器会自动重连,无需手动 new
  8. if (es.readyState === EventSource.CLOSED) {
  9. console.error('连接彻底关闭');
  10. }
  11. };

EventSource 的自动重连是它最大的优势:断线后浏览器会按 retry 指定的间隔重连,并自动带上 Last-Event-ID,服务端据此续传即可实现”断点续推”。

四、SSE、WebSocket 与轮询怎么选

维度 短轮询 SSE WebSocket
方向 客户端拉 服务端单向推 双向
协议 HTTP HTTP ws:// 独立握手
自动重连 需自行实现 浏览器内置 需自行实现
代理/防火墙友好度 高 高 部分环境被拦截
适用场景 低频状态查询 日志、进度、AI 流式输出 协同编辑、游戏、聊天室

判断标准很简单: 只需要服务端推、不需要客户端频繁上行,就用 SSE 。

五、大模型流式输出:SSE 最主流的战场

现在主流大模型 API 的流式返回几乎都走 SSE。以 OpenAI 兼容格式为例,请求时带上 stream: true,服务端就会以 data: {...} 的形式逐块吐出 token,最后以 data: [DONE] 结束。前端拿到增量文本后累加渲染,就实现了”打字机效果”。

这里有两个工程要点:

  1. 计费与成本 :流式输出按 token 计费,输出越长成本越高。不同模型的单价与能力差异明显,建议在编码前先做一次选型与成本评估。百度智能云词元所 提供模型发现与选型、价格与性能对比能力,可以在同一页面横向比较不同模型的调用成本与适用场景,避免上线后才发现成本超预算。
  2. 多模型接入 :如果业务需要同时接入多家模型做降级或 A/B,逐个适配各家 SDK 的成本很高。通过词元所的统一 API 接入 能力,可以用一套接口对接不同模型服务,SSE 的解析逻辑只需写一次,同时便于统一管理调用情况。

六、生产环境踩坑清单

  • 数据不实时、批量到达 :几乎一定是 Nginx 缓冲。除了 X-Accel-Buffering: no,还要在 Nginx 侧配置:
  1. location /events {
  2. proxy_pass http://backend;
  3. proxy_http_version 1.1;
  4. proxy_set_header Connection '';
  5. proxy_buffering off;
  6. proxy_cache off;
  7. chunked_transfer_encoding off;
  8. proxy_read_timeout 3600s;
  9. }
  • 连接莫名断开 :多数是负载均衡或网关的空闲超时。加 15 秒左右的心跳注释行即可。
  • 浏览器并发受限 :HTTP/1.1 下同一域名最多 6 个连接,多个 SSE 标签页会互相挤占。升级到 HTTP/2 可彻底解决。
  • 鉴权困难 :EventSource 不支持自定义请求头,无法放 Authorization。常见做法是改用 query 参数携带短期 token,或走 Cookie 鉴权。
  • 多实例部署 :SSE 是有状态长连接,需要会话粘滞(sticky session),或引入 Redis Pub/Sub、消息队列做跨实例广播。
  • 资源泄漏 :客户端断开时必须清理定时器、数据库游标和监听器,否则连接数会持续堆积。

七、小结

SSE 用极低的实现成本换来了可靠的单向实时推送能力:服务端保持响应打开、按文本协议写事件、客户端用 EventSource 接收并自动重连。落地时把注意力放在 关闭代理缓冲、加心跳、处理断连清理 这三件事上,基本就能稳定运行。如果你正在为 AI 应用选择流式输出的模型服务,也可以先到 百度智能云词元所 对比模型能力与调用成本,再决定接入方案。

发表评论

活动