SSE流式传输实战：从协议原理到生产环境踩坑指南

1. 从 AI 逐字输出说起：为什么我放弃了轮询

如果你最近做过任何大模型相关的前端对接，大概率见过那个经典画面：AI 的回复不是一次性跳出来的，而是一个字一个字往外蹦。第一次看到这个效果的人会觉得挺神奇，但做技术的人都会下意识问一句：这到底是怎么实现的？

答案十有八九是 SSE——Server-Sent Events，服务端推送事件。SSE 是一种基于 HTTP 的流式传输协议，服务端可以持续不断地把数据推给客户端，客户端不需要反复发请求。它和 WebSocket 常被放在一起比较，但在"AI 回复逐字输出"这个场景里，SSE 几乎是最优解，理由后面我会详细说。

这篇文章不打算写成协议文档翻译稿，我想以一个实际做过流式接口的开发者视角，把这几个问题讲透：SSE 的报文格式到底怎么组织、服务端和客户端怎么写才能直接跑、流式 Markdown 渲染怎么做才不糊、以及上线之后最容易踩的坑是哪些。无论你是后端要开一个流式接口，还是前端要接一个流式接口，这篇应该都能帮上忙。

在开始之前先给个结论：SSE 不是什么新技术，2009 年就在 HTML5 规范里出现过，但过去很多年被 WebSocket 的光芒盖住了。直到大语言模型带火了"流式输出"，SSE 才被重新捡起来，而且越用越香。核心原因就三个字：够简单。

1.1 轮询方案的困境

在没有 SSE 之前，想让网页实时刷新数据，最常见的做法是轮询。前端开一个 setInterval，每秒钟或者每三秒钟向后端发一次请求，问一句"有数据了吗"。后端查一下，有就返回，没有就返回空。

这种做法在数据量小、更新不频繁的场景下勉强能跑，但一旦遇到"逐字输出"这种场景，问题就非常明显。假设 AI 生成一段 200 字的回复，客户端要实时展示，如果每 3 秒轮询一次，那么用户体验就是"卡一下、冒一段、卡一下、冒一段"，根本不像是流式。如果缩短到 500 毫秒轮询一次，服务端压力会暴涨——大多数请求其实都拿不到新数据，白白消耗带宽和数据库连接。更麻烦的是，高频轮询会带来明显的延迟，每次请求都要走完整的 HTTP 握手、鉴权、业务处理、返回，这个链路再怎么优化也有底噪。

长轮询（Long Polling）是轮询的一种改良版，客户端发请求后服务端挂住连接，有新数据才返回，然后客户端再次发起请求。延迟问题确实改善了不少，但实现起来本身就有一套复杂的逻辑，而且每次重新建立连接都要重新做一次鉴权和初始化状态，在真正的多轮流式输出场景里，状态维护会变得很痛苦。

1.2 SSE 的真正价值：一条 HTTP 连接，持续推送到关闭

SSE 解决的问题，就是用一个长连接替代无数个短请求。客户端通过 EventSource 对象发起一次 HTTP 请求，服务端收到后不立即返回完整响应，而是维持这个连接，把数据切成一段一段，每段写完就通过 flush 推给客户端。客户端收到一段就渲染一段，直到服务端主动关闭连接，或者网络异常导致连接断开。

这个模型的好处在于：

• 延迟极低：服务端每生成一小段数据，能立刻推到客户端，用户感知到的就是"字在蹦"。
• 连接开销小：一条连接从头用到尾，不用反复握手。
• 天然基于 HTTP：不需要额外协议升级，走 80/443 端口就能穿透绝大多数防火墙，对基础设施的侵入性极低。
• 自动重连：浏览器原生的 EventSource 内置断线重连机制，不用自己写心跳和重连逻辑。

当然它也有短板，比如服务端不能向客户端主动发送任意消息——实际上如果连接建立后服务端随时可以推，不需要客户端再发请求；但相比 WebSocket 的双向通信，SSE 是单向的，客户端想给服务端传数据得另走普通 HTTP 请求。另外浏览器对并发 HTTP 连接数有限制，一个域名下同时开太多 SSE 连接会触发浏览器限制，这个后面单独讲。

2. text/event-stream 协议拆解：SSE 的报文长什么样

很多人在实现 SSE 时，第一步就栽在"不知道服务端到底该返回什么格式"。其实 SSE 的报文格式非常规整，就是纯文本，但每一行都有严格约定。理解了这个格式，后面写代码就是水到渠成的事。

2.1 一个最简单的 SSE 报文

假设我启动了一个 SSE 服务，访问 /api/stream，返回的 Content-Type 是 text/event-stream，响应体长这样：

code复制data: 第一条消息

data: 第二条消息

data: 第三条消息

注意几个关键点：每条消息以 data: 开头，后面跟消息内容；每条消息以一个空行结束；一个空行表示一条消息的终止。也就是说，data: xxx\n\n 构成一条完整的消息。如果是多行内容，可以拆成多个 data: 行，浏览器会把这几个 data: 行的内容拼接成一个消息体，中间用换行符连接。

code复制data: 第一行
data: 第二行

这条消息实际接收到的 event.data 是 "第一行\n第二行"。

2.2 data、id、event、retry 字段怎么用

SSE 协议定义了五个字段，平时最常用的是 data 和 id，偶尔用 event 和 retry，还有个 : 开头的注释行。

data 是消息内容，不多解释。id 是消息编号，字符串类型，客户端会自动记录最近一次收到的 id。如果连接断了，客户端自动重连时，会在请求头里带上 Last-Event-ID，服务端可以通过这个头判断"用户已经收到哪条了，接下来从哪条开始发"。这在断线续传场景里非常有用，尤其是消息量大、不允许重复推送的业务。

event 用来定义事件类型。不加 event 时，消息默认触发 EventSource 的 onmessage；加了 event，客户端需要用 addEventListener 监听对应事件名。

code复制event: user_login
data: {"user_id": 12345}

retry 用来告诉浏览器重连间隔，单位是毫秒。比如希望断线后 5 秒再重连，可以在服务端消息里加一行：

code复制retry: 5000

注意，retry 可以单独作为一条消息发，也可以和 data 混在同一条消息里。

2.3 注释行：保活心跳的隐藏角色

: 开头的一行，协议上叫注释（comment）。客户端收到注释行会直接忽略，不会触发任何事件。那为什么还要发它？

因为很多网络中间设备（代理、负载均衡器）会在连接空闲一定时间后自动断开。如果服务端长时间不发数据，连接可能被静默切断，而双方都感知不到。解决办法就是每隔十几秒发一条注释行，比如 : heartbeat，维持连接活跃。浏览器收到注释行发现没有实际消息，不会有任何副作用，但连接被保住了。

这个技巧在很多生产级 SSE 实现里都会用。我在实际项目里的做法是单独开一个定时器，每 15 秒往响应流里写一行 : heartbeat\n\n。后面踩坑章节我会再细讲，因为如果不做心跳，你会在线上看到大量莫名其妙的连接中断。

3. 服务端实现：Node.js 和 Python 两个能直接跑的版本

原理讲清楚之后，直接上代码。这两个版本我都实际用过，也都是社区里最常见的写法，可以直接抄。

3.1 Node.js 版本（Express）

用 Node.js 写 SSE 有个天然优势——HTTP 响应本身就是一个流，res.write() 天然支持分段写出，不需要额外的库。唯一要做的就是把响应头设置正确。

javascript复制const express = require('express');
const app = express();

app.get('/api/stream', (req, res) => {
  // 关键：设置 SSE 对应的 Content-Type
  res.writeHead(200, {
    'Content-Type': 'text/event-stream',
    'Cache-Control': 'no-cache',
    'Connection': 'keep-alive',
    // 关键：如果服务放在 Nginx 后面，这个头能关掉 Nginx 的缓冲
    'X-Accel-Buffering': 'no'
  });

  let id = 0;
  const send = (data, event) => {
    if (event) {
      res.write(`event: ${event}\n`);
    }
    res.write(`id: ${id}\n`);
    res.write(`data: ${JSON.stringify(data)}\n\n`);
    id++;
  };

  // 每秒钟推一条数据，模拟流式效果
  const timer = setInterval(() => {
    send({ timestamp: Date.now(), message: `这是第 ${id} 条消息` });
  }, 1000);

  // 客户端断开时，必须清理定时器，否则会内存泄漏
  req.on('close', () => {
    clearInterval(timer);
    res.end();
    console.log('客户端已断开，连接清理完成');
  });
});

app.listen(3000, () => {
  console.log('SSE 服务已启动: http://localhost:3000/api/stream');
});

这里有几个细节值得注意。Cache-Control: no-cache 是必须的，否则部分浏览器或代理会缓存响应，导致拿不到后续数据。X-Accel-Buffering: no 是给 Nginx 看的，如果不加，Nginx 会默认缓冲响应，导致流式数据攒到一定量才转发给客户端，流式效果直接失效。这个坑我后面专门讲。

req.on('close') 是必不可少的资源清理逻辑。客户端断开连接后，如果服务端还在继续往响应流里写数据，虽然 write 本身不会报错（数据会进到系统缓冲区），但定时器会一直跑，造成连接对象和定时器的泄漏。在长连接场景下，泄漏的积少成多会非常可怕。

3.2 Python 版本（FastAPI）

Python 这边我推荐 FastAPI，它自带 StreamingResponse，配合异步生成器写 SSE 非常干净。

python复制from fastapi import FastAPI
from fastapi.responses import StreamingResponse
import asyncio
import json

app = FastAPI()

async def event_generator():
    id = 0
    try:
        while True:
            data = {
                "id": id,
                "timestamp": __import__("time").time(),
                "message": f"这是第 {id} 条消息"
            }
            # SSE 报文格式：id 行 + data 行 + 空行
            yield f"id: {id}\n"
            yield f"data: {json.dumps(data, ensure_ascii=False)}\n\n"
            id += 1
            await asyncio.sleep(1)
    except asyncio.CancelledError:
        # 客户端断开时，FastAPI 会取消生成器
        print("客户端已断开，生成器被取消")
        raise

@app.get("/api/stream")
async def stream():
    return StreamingResponse(
        event_generator(),
        media_type="text/event-stream",
        headers={
            "Cache-Control": "no-cache",
            "Connection": "keep-alive",
            "X-Accel-Buffering": "no",
        }
    )

FastAPI 的 StreamingResponse 会自动处理 media_type 和相关头，但 X-Accel-Buffering 这类自定义头必须在 headers 里显式声明。还有一个细节是 ensure_ascii=False，不然 json.dumps 会把中文转成 \uXXXX 转义序列，虽然协议上没问题，但客户端拿到之后还需要解码，调试时看报文也费劲。

3.3 服务端连接的生命周期管理

写 SSE 服务端时，我习惯把"连接生命周期"单独拆出来考虑，而不是把逻辑全堆在路由函数里。

一个完整的 SSE 连接生命周期包含四个阶段：建立、推送、保活、关闭。

建立阶段要做的是设置正确的响应头、完成业务鉴权。这里有个实践问题——EventSource 客户端默认不能携带自定义请求头，所以很多开发者的第一反应是"SSE 怎么做登录鉴权？"。常见的做法有两种：一种是把 token 放在 URL 的 query 参数里，服务端从 req.query.token 取；另一种是先用普通请求做鉴权并种下 Cookie，EventSource 会自动带上同源的 Cookie，服务端从 Cookie 里取用户身份。两种我都用过，第一种实现简单但 token 会出现在访问日志里，第二种更规范，但要确保服务端支持 Cookie 鉴权。

推送阶段就是持续生成业务数据并 write 到响应流。保活阶段就是我们前面说的 : heartbeat 注释行。关闭阶段则要处理"服务端主动关"和"客户端断开"两种情况：服务端完成推送后调用 res.end()，客户端断开时通过 req.on('close') 或生成器的 CancelledError 做清理。

4. 客户端接入：EventSource 的便利与局限

服务端写得再好，客户端接不对也是白搭。前端接入 SSE 有两条路：原生 EventSource，以及用 fetch 手动解析流。两者各有适用场景。

4.1 EventSource 基础用法

浏览器原生 EventSource 是接 SSE 最省事的方案，没有之一。它自动处理连接建立、消息接收、断线重连，连心跳探测都内置了。

javascript复制const eventSource = new EventSource('/api/stream');

// 连接建立
eventSource.onopen = () => {
  console.log('SSE 连接已建立');
};

// 默认消息事件（没有指定 event 字段的消息）
eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('收到消息:', data);
};

// 自定义事件类型
eventSource.addEventListener('user_login', (event) => {
  const data = JSON.parse(event.data);
  console.log('用户登录事件:', data);
});

// 连接异常（包含服务端主动关闭的情况）
eventSource.onerror = (error) => {
  console.error('SSE 连接出错:', error);
};

// 手动关闭连接
// eventSource.close();

这里有个容易误会的点：onerror 并不代表连接彻底失败了。在连接正常关闭时，EventSource 也会触发 onerror，然后自动进入重连流程。如果你在 onerror 里写了"提示用户网络异常"的逻辑，那么服务端正常推完数据关闭连接时，用户会看到一条莫名其妙的报错。

正确的处理方式是判断 eventSource.readyState。EventSource.CLOSED 表示连接已关闭，EventSource.CONNECTING 表示正在重连。排查问题时，把 readyState 打印出来是最直接的定位手段。

4.2 自动重连与 last-event-id

EventSource 的自动重连是"开箱即用"的，但有个前提——服务端必须配合 id 字段。浏览器在重连时，会自动在 HTTP 请求头里带上 Last-Event-ID: <你收到的最后一个 id>。服务端读到这个头，就知道该从哪条消息开始续传。

用 Node.js 举例，服务端可以这样处理：

javascript复制app.get('/api/stream', (req, res) => {
  const lastEventId = req.headers['last-event-id'];
  // 有 last-event-id 说明是断线重连，从指定位置开始续传
  let startId = lastEventId ? parseInt(lastEventId, 10) + 1 : 0;
  // ...业务逻辑
});

这个特性在处理长任务时特别有用。比如一个要跑 5 分钟的任务，期间客户端断网重连，如果没有 last-event-id 续传机制，客户端只能从头开始重新收，前面收到的全白费。有了它，服务端可以在内存里缓存最近的消息，重连时从断点继续推。

不过要注意，last-event-id 是一个 HTTP 请求头，不是 SSE 报文里的字段。调试时要看请求头，不是看响应体。

4.3 需要带请求头时：用 fetch 自己解析流

EventSource 最大的限制就是不能自定义请求头，连 Authorization 都设置不了。如果你需要 token 鉴权，又有一些场景不想把 token 放 URL 里，可以用 fetch 配合 ReadableStream 手动解析。

javascript复制const response = await fetch('/api/stream', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

if (!response.ok) {
  throw new Error(`连接失败: ${response.status}`);
}

const reader = response.body.getReader();
const decoder = new TextDecoder('utf-8');
let buffer = '';

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

  buffer += decoder.decode(value, { stream: true });

  // SSE 消息以空行（\n\n）分隔，按这个去切分
  const parts = buffer.split('\n\n');
  buffer = parts.pop(); // 最后一段可能是不完整的半条消息，留到下一轮

  for (const part of parts) {
    for (const line of part.split('\n')) {
      if (line.startsWith('data: ')) {
        const payload = line.slice(6);
        console.log('收到消息:', payload);
      }
    }
  }
}

这段代码的核心是流式解析：每次 read() 返回的 value 不一定正好是一整条 SSE 消息的边界，可能是半条，也可能包含多条。所以要先累积到一个 buffer 里，用 \n\n 切分，完整的消息立刻处理，不完整的留到下一轮。这个"攒、切、留尾"的处理逻辑是手写流解析的基本功，很多框架底层也是这么干的。

用 fetch 的好处是能自定义请求头、能拿到响应状态码、能做更细粒度的错误处理。代价是自动重连、自动解析都没了，都要自己实现。我的建议是：能用 EventSource 就尽量用 EventSource，只有碰到必须带自定义头的接口才切换到 fetch 方案。

5. 流式 Markdown 渲染：让 AI 回复"边写边排版"

SSE 在 AI 领域的典型场景是流式输出 LLM 生成的文本，而这些文本大部分是 Markdown 格式。这就带来一个之前没怎么遇到的问题：Markdown 在写一半的时候，语法是不完整的。

5.1 流式 Markdown 的难点：半截语法

想象一下，模型正在输出一段代码块：

code复制```javascript
const a = 1;
```

这个完整的内容只有写到末尾才能正确解析，但流式输出时，前端可能先收到的是：

java复制

或者更碎的一段：

code复制```java
const a = 
```

如果把这种半截内容直接丢给 Markdown 渲染器，结果就是：代码块标记没有闭合，整个页面后面的内容全被吞进代码块里，或者标题语法 # 刚写一个 # 就被渲染成标题。体验很差。

5.2 全量重渲染 + 节流的朴素方案

最简单粗暴的方案是：每收到一块新数据，就把累积的完整文本重新渲染一次。这个方案实现最简单，但有两个问题。

一是性能问题。Markdown 渲染有成本，如果消息频率很高（比如每 30 毫秒来一块），渲染器会被频繁调用，页面可能卡顿。解决办法是节流（throttle），比如限制每 100 毫秒最多重新渲染一次。

javascript复制let markdownBuffer = '';
let renderTimer = null;

function onChunk(chunk) {
  markdownBuffer += chunk;

  if (renderTimer) return;
  renderTimer = setTimeout(() => {
    renderTimer = null;
    renderMarkdown(markdownBuffer);
  }, 100);
}

二是中间态问题。全量重渲染时，如果当前文本正处在代码块中间，渲染器仍然会把它渲染成一个不完整的代码块，视觉上就是"突然出现一个代码块框，里面内容在变"。这是朴素方案绕不开的缺点。

5.3 稳定区/过渡区拆分：更顺滑的中间态

为了解决中间态的问题，我用的方案是把整个文本流拆成"稳定区"和"过渡区"两块。

具体思路是：每次收到新数据时，把累积文本按行切分，如果最后一行是"可能是 Markdown 语法半截"的行，就把它单独放进过渡区，前面的完整行放进稳定区。稳定区直接按正常 Markdown 渲染；过渡区用纯文本方式显示，等它变成完整行后再合并进稳定区。

举个例子，收到这样一段文本：

code复制# 标题
这是一段正文
- 列表项
- 还没写完

最后一行 - 还没写完 是不完整的一个列表项，它后面可能还会追加更多内容。于是我把前两行作为稳定区，渲染成完整的 Markdown；最后一行放在过渡区，作为一个普通文本行显示。当下一块数据到达时，如果 - 还没写完 后面有了新内容，它就合并进稳定区重新渲染，新的半截行再进入过渡区。

这个方案实现起来的核心是判断"哪一行可能是半截"。我的经验是，以下几类情况建议放进过渡区：

• 代码块分隔线 ``` 或 ~~~ 所在的行（因为在补全之前无法确定语言名称）
• 表格行（Markdown 表格需要完整的行结构才能正确渲染）
• 最后一行没有以两个换行符结束的行（说明可能还没写完）

判断逻辑很难做到完美，但 80% 的情况靠"最后一行是否以换行符结尾"这个规则就能覆盖。实际体验下来，过渡区方案已经足够顺滑，用户看到的视觉效果接近"边打字边排版"。

如果你不想自己实现这套逻辑，也可以直接用社区现成的库。比如 marked 或 markdown-it，配合上述的节流和过渡区策略，基本能覆盖大多数场景。

多提一句，热词里有人搜"在线sse客户端测试"、"sse流式输出markdown渲染器"，说明大家确实在自己在做这层工具。我做过的处理流程里，最省心的组合是：SSE 传输原始文本，前端把原始文本做增量渲染，后端不做任何 Markdown 处理。把 Markdown 渲染放在前端的好处是，服务端逻辑更纯粹，前端可以根据需要切换不同的渲染方案，不用改接口。

6. 调试姿势：curl 是第一步，在线工具是第二步

SSE 接口调试起来和普通接口不太一样，因为数据是流式到达的。我自己的调试顺序是从命令行开始，再到浏览器，最后用在线工具或自己写的小工具。

6.1 curl 验证协议本身

最快验证一个 SSE 接口是否正常的方法，就是 curl。加上 -N 参数禁用缓冲，让输出流式打印：

bash复制curl -N http://localhost:3000/api/stream

如果接口正常，你会看到数据一段一段地打印到终端：

code复制id: 0
data: {"id":0,"timestamp":1710000000,"message":"这是第 0 条消息"}

id: 1
data: {"id":1,"timestamp":1710000001,"message":"这是第 1 条消息"}

注意，curl 打印出来的就是最原始的 SSE 报文，包含 id: 前缀、data: 前缀和空行。如果这里能看到完整格式，说明服务端没问题，问题大概率出在中间链路（代理、网关）或客户端。

如果发现 curl 没有输出，但请求又没有报错，第一件事就是检查响应头。用 curl -i 看响应头里的 Content-Type 是不是 text/event-stream。很多新手把 Content-Type 写成了 application/json，浏览器端 EventSource 会直接报错。

6.2 在线 SSE 客户端测试工具

网上有一些在线 SSE 客户端测试工具，原理是让你填一个 SSE 接口 URL，然后实时渲染收到的消息。这类工具适合快速验证"我这个接口发给别人能不能通"，尤其适合前后端联调时使用——让后端把接口地址丢给前端，前端自己在测试工具里先确认数据格式，再写页面逻辑。

另外也可以用 Postman。新版 Postman 对 SSE 的支持已经很成熟了，创建请求时选择 text/event-stream，它就会以流式的方式展示收到的数据。Postman 的好处是能同时查看响应头和响应体，方便排查 Content-Type、缓存头等问题。

6.3 如何确认消息到底卡在哪一层

流式输出最让人头疼的排查场景是"接口通了，但数据不是实时的"。比如明明是流式接口，前端却要等好几秒才一次性拿到所有内容，或者要等整个响应结束才显示。这种情况绝大多数不是代码逻辑问题，而是中间链路的缓冲问题。

判断卡在哪一层的办法是逐层排查。第一步，用 curl -N 直连服务端，确认服务端本身是实时输出的。第二步，如果服务端前面有 Nginx 或网关，用 curl -N 走完整链路再测一次，看是否变成非实时。如果直连正常、走代理不正常，那问题就在代理层，去检查代理配置里的缓冲设置。

还有一个容易被忽略的点是压缩。部分服务器中间件会自动对响应做 gzip 压缩，压缩本身没问题，但某些压缩实现会攒够一定的数据量才输出一段，导致流式效果完全消失。排查时可以看看响应头里有没有 Content-Encoding: gzip。SSE 场景下我一般不推荐开启压缩，因为流式数据本身就是"持续小段输出"，压缩节省的流量有限，但带来的延迟和缓冲问题却很明显。

7. 生产环境踩坑记：代理缓冲、心跳与连接数

这一章写的全是我实际上线后踩过的坑，每一个都真实发生过，每一个都不难解决，但每一个都能让你排查到怀疑人生。

7.1 代理缓冲导致"攒一批才返回"

最典型的坑就是 Nginx 缓冲。默认情况下，Nginx 会缓冲后端响应，攒够一定字节数或者等后端关闭连接后才把数据转发给客户端。如果你的服务部署在 Nginx 后面，SSE 接口没有做任何额外配置，前端体验到的就是"转圈转很久，然后突然一次性全出来"。

解决办法有三个层面，按推荐顺序排：

第一，后端在响应头里加 X-Accel-Buffering: no，这是 Nginx 专门为 SSE 设计的头，告诉 Nginx 不要缓冲这个响应。我的 Node.js 和 FastAPI 示例里都已经加上了。

第二，在 Nginx 配置里针对 SSE 接口路径关闭缓冲：

nginx复制location /api/stream {
    proxy_pass http://backend;
    proxy_buffering off;
    proxy_cache off;
    proxy_set_header Connection '';
    proxy_http_version 1.1;
    chunked_transfer_encoding on;
    proxy_read_timeout 3600s;
}

这里 proxy_buffering off 是核心，proxy_read_timeout 3600s 是为了防止长时间没有数据时 Nginx 主动断开连接。如果项目里有网关层（比如 Kong、APISIX），同样要检查类似配置。

第三，如果服务端和 Nginx 都在自己手里，还有一个更彻底的做法——换用 HTTP/2 或直接走 WebSocket。但这就偏离 SSE 的初衷了，一般用前两个方案就够。

7.2 浏览器 6 连接限制

这个坑比较隐蔽。HTTP/1.1 下，浏览器对同一个域名最多同时建立 6 个 TCP 连接。如果页面上同时打开了多个 SSE 流（比如多开几个 AI 对话窗口），第 7 个 SSE 连接会一直停留在 pending 状态，直到前面的连接关闭。

在 HTTP/1.1 时代，这个问题没有办法根治，只能从架构上规避。一个常见做法是把不同类型的 SSE 连接分散到不同的子域名，比如 stream1.example.com、stream2.example.com，每个子域名独立计算 6 连接限制。另一个做法是尽量避免一个页面同时开多个 SSE，把多个数据流合并到一个连接里，客户端根据消息类型分发。

HTTP/2 没有这个 6 连接限制，因为 HTTP/2 的多路复用允许在同一个 TCP 连接上并发多个流。如果你的部署环境支持 HTTP/2，这个坑就自然消失了。我在实践中的建议是：如果 SSE 并发量预期会比较大，尽量让网关启用 HTTP/2。

7.3 心跳、超时与资源清理

看似不重要的心跳，在生产环境里是救命稻草。我之前维护的一个服务，SSE 连接每开一段时间就悄无声息地断掉，客户端收不到数据，服务端也不知道连接已经失效。排查到最后，发现是云平台的四层负载均衡器有一个空闲超时机制，连接空闲超过 60 秒就会被静默回收。

解决办法就是加心跳。服务端开一个定时器，每 15 秒写一行 : heartbeat\n\n。这几行注释本身不携带业务数据，但能保证 TCP 连接一直在"活跃"状态，负载均衡器不会因为空闲而切断它。

javascript复制const heartbeatTimer = setInterval(() => {
  res.write(': heartbeat\n\n');
}, 15000);

另外，生产环境一定要处理"客户端断线但服务端还在写"的情况。Node.js 里 req.on('close') 是可靠的信号，但要记住：res.write() 在连接已断开时不会立刻抛异常，数据只是被写进了内核缓冲区。如果不做检查，定时器会一直运行，内存和连接对象会不断累积。我在线排查过的一个事故，就是这个原因导致 Node.js 进程的句柄数暴涨到十几万，最后进程崩溃。处理方式其实很简单：在 close 事件里 clearInterval 并 res.end()，必要时还要把业务处理中的异步任务一起取消。

7.4 我个人的几条习惯

最后分享几条我做 SSE 接口时养成的固定习惯，不一定适合所有项目，但至少帮我避免了几次线上事故。

第一，所有 SSE 接口统一走一个基类或中间件。 把响应头设置、心跳、连接清理这些公共逻辑封装一遍，业务代码只管往流里写数据。这样即使以后要改心跳间隔，也只需要改一处。

第二，消息统一用 JSON 字符串封装。 虽然 SSE 报文支持纯文本的 data: 行，但纯文本的可扩展性太差。我一般固定用 data: {"type":"delta","content":"..."} 这种结构，后期加字段不需要改协议。

第三，给消息编号不要用自增整数之外的东西做断点。 id 字段最好用单调递增的序号，这样 Last-Event-ID 续传逻辑最简单可靠。如果用时间戳做 id，在消息生成很快时可能撞出重复值，续传判断就会出问题。

第四，前端接入时一定要做超时兜底。 虽然 EventSource 自带重连，但如果网络长时间没有数据，重连机制也不会自动触发。我习惯在前端加一个空闲超时检测，比如超过 30 秒没有收到任何消息（包括心跳可能没有转发的情况），就主动 close() 再重新 new EventSource()。

第五，SSE 接口的日志要单独打。 SSE 连接通常持续时间长，期间可能有大量消息推送，如果把每一条消息都打到常规日志里，日志量会爆炸。我的做法是只记录连接建立、断开、异常这三个节点，消息内容不记录，只统计推送条数和总字节数，出问题时再按需开启详细日志。

写完这些，回头看看，SSE 本质上不是一个复杂的技术，它比的不是谁懂的多，而是谁在细节上想得周全。协议格式固定，服务端写法也不复杂，真正区分一个流式接口好不好用，全看生产环境里那些不起眼的边角——缓冲关没关、心跳有没有、断线重连顺不顺、资源清理干净不干净。从轮询到 SSE，从半截 Markdown 到增量渲染，每一步的取舍其实都是在回答同一个问题：怎么让用户觉得这个系统是"活"的。想清楚了这个，技术选型也就没那么纠结了。