这个系列写到第105篇我越来越觉得很多基础协议才是最值得写透的东西。就拿SSEServer-Sent Events来说表面上看浏览器端就一个EventSource对象好像没什么可讲的可真到了线上环境你会发现“解析、重连、中止”这三个环节每一个都有大量的坑等着你踩。尤其是最近一两年大模型流式输出带火了AI应用大家又开始频繁使用SSE来推送token各种奇奇怪怪的问题也随之冒出来。比如服务端报错里经常出现“stream disconnected before completion: idle timeout waiting for sse”又比如不少人在用Codex这类AI编程工具时反复遇到“重连5次”的情况其实这些都和SSE在浏览器端的连接管理机制有直接关系。这篇文章我只聊浏览器侧把SSE从连接建立、数据解析、断线重连到主动中止的整个生命周期拆开讲一遍。适合前端、全栈、正在做AI应用或实时通知系统的朋友参考尤其是那些被EventSource坑过、又想搞清楚原理的人。文章里所有结论都来自我自己的实际项目和线上的排查记录不是纯理论堆砌你可以直接拿去对照自己的代码。1. 内容整体设计与思路拆解1.1 先明确SSE在浏览器里的真实定位SSE全称Server-Sent Events是HTML5规范里定义的一种服务器推送技术。它本质上还是HTTP只不过服务端在响应时把Content-Type设置为text/event-stream然后通过这条HTTP连接持续向浏览器写数据。浏览器拿到的是一个流式响应可以一边接收一边解析而不是等所有数据都传输完再一次性处理。打个比方SSE就像一台收音机服务器是电台浏览器是收音机。频道是单向的服务器说什么你就听什么你无法通过这条线路回话。WebSocket则是电话双方都能随时说话。正因为SSE是单向的它在很多场景下反而更合适只推送通知、只流式输出文本、只同步状态不需要客户端频繁回传数据。比如AI聊天机器人逐字输出回答、股票行情推送、后台任务进度条、在线日志流都用SSE非常自然。浏览器对SSE的原生支持就是EventSource对象它帮我们封装了连接管理、事件分发和自动重连。这是我觉得SSE对比WebSocket最舒服的地方——你用WebSocket还得自己写心跳、自己处理重连的爆炸问题用EventSource基本是开箱即用。1.2 解析、重连、中止为什么是三个独立问题很多人把SSE当作一个整体去看出了错不知道怎么定位。我的经验是一定要把浏览器端的SSE生命周期拆成三件事来分析。解析解决的是“浏览器收到这些文本后如何正确转成可编程的事件”。这里涉及SSE数据格式的语法细节比如data:、event:、id:、retry:这些字段的含义多行data的拼接规则以及消息边界怎么判定。解析出错前端往往连报错都没有就是收不到想要的数据。重连解决的是“连接断了之后浏览器和服务端如何恢复到正确状态”。浏览器有自动重连机制但默认策略符不符合你的业务场景服务端要不要配合Last-Event-ID做续传这是需要认真设计的。中止解决的是“连接不再需要时怎么安全、彻底地关闭”。别小看这一步我见过太多线上事故就是因为前端页面切走了SSE连接没关服务端连接池被占满最后整个服务不可用。这篇文章的主体结构就按照“解析、重连、中止”三个核心环节展开再加上鉴权、连接数这类在实际项目里绕不开的限制问题最后落到一份常见问题排查实录。每一块我都会给代码、给场景、给原因尽量让大家看完就能在项目里用起来。2. 核心细节解析与实操要点2.1 SSE报文格式里的那些“隐藏规则”浏览器怎么解析SSE先说数据格式。服务端返回的每一行如果是字段行基本格式是“字段名: 字段值”。字段名有四种data、event、id、retry。以冒号开头的行是注释行浏览器会直接忽略。一条消息以空行结束。注意这个空行是必须的。如果服务端没有在消息末尾输出空行浏览器就会一直把后续内容当成同一条消息的延续导致前端的事件迟迟不触发。我在项目中就遇到过服务端漏加空行的情况表现就是数据发了很多条前端却一条事件都没收到。排查了大半天最后抓包看原始响应才找到问题。data字段可以出现多次浏览器会把同一块消息里的多行data用换行符拼接起来。比如data: 第一行 data: 第二行浏览器侧拿到的消息内容是第一行\n第二行不是第一行第二行。很多新人在这里栽跟头以为多行data会自动拼成一行。如果你的业务数据里本身就包含换行这么设计其实很合适但如果你只是想分块传输一段长文本就得自己注意拼接逻辑。event字段指定该消息的事件类型。如果省略浏览器会触发默认的message事件如果写了event: custom你就得用addEventListener(custom, handler)来监听。这块要注意一个小坑如果某条消息没有event字段但你同时监听了message和自定义事件浏览器只会触发message不会重复触发其他事件。id字段用来标注消息编号它和重连机制强相关。浏览器会记住拿到的最新一条消息的id在重连时通过请求头Last-Event-ID带回给服务端。retry字段则告诉浏览器连接断开后等待多少毫秒再重连。2.2 浏览器端的事件分发机制用代码来看浏览器端最基础的SSE用法就三行const eventSource new EventSource(/api/sse); eventSource.onmessage (event) { console.log(event.data); }; eventSource.onerror (event) { console.error(连接发生异常, event); };EventSource内部维护了一个readyState属性有三种状态CONNECTING值为0、OPEN值为1、CLOSED值为2。连接建立成功后进入OPEN状态监听到onopen回调。断开后如果还没有手动close()它会自动回到CONNECTING状态并尝试重连。如果你需要区分不同类型的事件用addEventListener更灵活const eventSource new EventSource(/api/events); eventSource.addEventListener(message, (e) { // 处理默认事件 }); eventSource.addEventListener(heartbeat, (e) { // 处理自定义事件heartbeat }); eventSource.addEventListener(error, (e) { // 注意这里的error事件既包含协议错误也包含网络断开 });实际项目里我习惯把业务事件分成几类比如connection_established、message、heartbeat、error这样代码逻辑会清晰很多。还有一点很重要如果服务端发来的数据不是合法的UTF-8文本或者格式不完整浏览器会直接忽略这一块数据甚至触发error事件前端要做好兜底。2.3 解析过程中的高频坑从我接触过的项目来看SSE解析阶段有这么几个高频问题提前说出来帮你避坑。第一最后一行没有空行。这是最低级也最常见的错误。很多服务端框架在写完一条消息后忘记额外输出一个空行结果就是浏览器认为消息还没结束事件永远不触发。第二数据里混入了BOMByte Order Mark。如果服务端返回文本前带了一个UTF-8 BOM头浏览器在解析第一条数据时可能把这个BOM字符带进事件名或数据里导致你监听的事件名对不上。解决方法是服务端统一使用无BOM的UTF-8输出。第三代理层缓冲导致消息延迟。SSE依赖流式传输但有些Nginx或网关默认会缓冲响应攒够一定字节才往客户端推。表现就是前端不是一条条收到数据而是过很久突然收到一大坨。解决办法是让服务端在响应头里加X-Accel-Buffering: noNginx看到这个头会关闭对该响应的缓冲。如果你是直接调的云厂商网关也需要在文档里找一下怎么关闭缓冲。第四用fetch手写SSE容易漏处理编码问题。后面我会单独讲fetch ReadableStream的方案这里先提醒一下直接用fetch读流的时候很多后端返回的是application/octet-stream或者其他Content-Type你没有声明text/event-stream也别慌只要你自己解析文本流就行但字符编码必须统一用UTF-8否则中文会乱码。3. 实操过程与核心环节实现3.1 用EventSource建立连接的完整流程先给一个标准的前端接入样例。假设服务端接口是GET /api/stream返回text/event-stream// 建立连接 const eventSource new EventSource(/api/stream); // 连接打开 eventSource.onopen () { console.log(SSE连接已打开); }; // 监听默认消息 eventSource.onmessage (e) { const data JSON.parse(e.data); renderMessage(data); }; // 监听错误 eventSource.onerror (e) { if (eventSource.readyState EventSource.CLOSED) { console.log(连接已关闭不再自动重连); } else { console.log(连接异常浏览器正在自动重连); } };这里有个关键点onerror回调并不一定代表连接彻底失败。在网络抖动或服务端重启时readyState通常会变成CONNECTING浏览器会按照retry字段或默认值自动重连。只有当你手动调用了close()或者服务端返回了某些明确不可恢复的错误码readyState才会变为CLOSED。服务端那边一个最简单的Node.js实现是这样const http require(http); http.createServer((req, res) { if (req.url /api/stream) { res.writeHead(200, { Content-Type: text/event-stream, Cache-Control: no-cache, Connection: keep-alive, X-Accel-Buffering: no }); let id 0; const timer setInterval(() { id; // 注意每条消息之间必须有空行 res.write(id: ${id}\n); res.write(data: ${JSON.stringify({ time: Date.now() })}\n\n); }, 1000); req.on(close, () { clearInterval(timer); res.end(); }); } else { res.end(ok); } }).listen(3000);这段代码里每一秒推送一条消息每条消息都带id字段这样浏览器重连时就能通过Last-Event-ID实现续传。req.on(close)是服务端感知连接关闭的关键在这个回调里清理定时器和其他资源否则服务端会一直尝试往一个已经死掉的连接上写数据白白消耗内存和CPU。3.2 从“重连5次”与idle timeout谈重连策略设计热词里反复出现“codex重连5次”和“stream disconnected before completion: idle timeout waiting for sse”这两个现象实际上是同一个底层问题的不同侧面值得展开讲一下。先说idle timeout waiting for sse。这个报错我最早是在对接OpenAI等大模型流式接口时看到的。它的含义是服务端在等待流下载完成的过程中等了太久都没等到数据或迟迟没有完成传输触发了空闲超时于是主动断开连接。为什么会空闲可能有两种情况一是网络链路中某个环节比如Nginx设置了proxy_read_timeout默认值常常是60秒如果SSE连接在60秒内没有任何数据推送代理就认为连接空闲了直接切断二是服务端自己写了超时逻辑长时间没有业务数据就断开。解决办法有三个层面第一调整代理和服务端的超时时间。如果你用Nginx做反向代理可以在location配置里加location /api/stream { proxy_pass http://backend; proxy_http_version 1.1; proxy_set_header Connection ; proxy_buffering off; proxy_cache off; proxy_read_timeout 1h; }proxy_read_timeout 1h是给SSE连接设置一小时的读取超时实际项目中可以根据你的业务推送频率去调整。proxy_buffering off和proxy_set_header Connection 是为了避免Nginx缓冲和HTTP/1.0连接复用带来的问题。第二服务端必须加心跳。即使没有业务数据也要定期往连接里写一个注释行保持连接活跃。注释行会被浏览器忽略不会触发任何事件但能让所有中间层看到“数据还在流动”: heartbeat ping我在项目里一般设置30秒发一次心跳注释这样即使业务数据稀疏连接也不会被空闲超时掐断。如果你用EventSource注释行同样有效浏览器不会把它当作消息最多在浏览器开发者工具里看到网络面板有数据在持续跳动。第三前端不要只依赖EventSource的默认重连。默认的自动重连是固定间隔、无限次数这在很多场景下并不合适。比如用户在断网状态下浏览器会一直尝试重连但实际上网络没恢复重连只会白白消耗资源和产生大量错误日志。更合理的策略是自己控制重连逻辑设置重试次数上限比如3到5次配合指数退避。所谓指数退避就是第一次重连等1秒第二次等2秒第三次等4秒再加一点随机抖动避免大量客户端同时重连造成服务端被冲垮这在突发断网恢复时尤其重要。一个自定义重连的参考写法function connectWithRetry(url, maxRetries 5) { let retries 0; function connect() { const es new EventSource(url); es.onopen () { retries 0; // 连接成功则重置重试次数 }; es.onerror () { es.close(); // 先关闭当前的EventSource避免浏览器自动重连干扰 if (retries maxRetries) { const delay Math.min(1000 * Math.pow(2, retries) Math.random() * 1000, 15000); retries; setTimeout(connect, delay); } else { showOfflineTip(); } }; return es; } return connect(); }注意这里的思路在onerror里先手动es.close()禁用浏览器的自动重连再用自己的退避算法决定何时重连。这样就完全掌控了重试次数和间隔不会再出现“无限重连5次”之后毫无人性化的提示也不会让用户在断网环境里看着一堆红色报错刷屏。另外重连时要考虑消息补偿。如果服务端在每条消息里都带上了id字段浏览器自动重连时会带上Last-Event-ID。但如果你走的是自己实现的重连先close()再重新new EventSourceLast-Event-ID可能就没了因为浏览器只在同一次EventSource生命周期内的自动重连才会自动带上这个请求头。所以自定义重连一定要自己在URL上带上次ID参数或者通过其他方式告诉服务端。最简单的做法是在前端维护一个变量lastEventId在onmessage时更新它重连时拼到URL查询串里new EventSource(/api/stream?lastId lastEventId)。服务端根据这个参数决定从哪里开始继续推。3.3 中止连接的正确姿势与资源治理浏览器主动中止SSE连接只有一个APIeventSource.close()。调用之后readyState变为CLOSED浏览器不再自动重连底层TCP连接也会关闭。这个API很简单但真正的难点在于“什么时候要中止”和“中止之后如何保证服务端资源也释放”。我最常说的一个场景就是前端框架里的组件卸载。比如你写了一个React组件在useEffect里建立了SSE连接组件没挂载了但连接还开着这会造成两个问题一是客户端连接泄漏页面反复进出的场景下每进出一次就多一条连接最后浏览器同一域名下的连接数被占满其他请求全部排队卡死二是服务端资源被白白占用服务端每维护一条SSE连接都要占用文件描述符和内存连接多了直接把服务拖垮。正确的React写法是这样的useEffect(() { const eventSource new EventSource(/api/stream); eventSource.onmessage (e) { setData(JSON.parse(e.data)); }; // 组件卸载时关闭连接 return () { eventSource.close(); }; }, []);这段代码的关键在return () { eventSource.close(); }。React会在组件卸载阶段执行这个清理函数把SSE连接关掉。Vue的onUnmounted也是同样的道理一定要在销毁钩子里把连接关掉。除了组件卸载还有一种情况是页面切到后台但不关闭。Chrome对后台页面的定时器有节流机制但对EventSource这种网络请求本身不会强制中断。如果你发现页面切到后台一段时间后SSE连接断了有可能是网络环境变化也可能是服务端的保活机制不够健壮。一个稳妥的做法是监听visibilitychange事件页面进入后台时主动close()回到前台时重新建立连接。这样做的好处是避免后台页面占用连接资源特别适合移动端。document.addEventListener(visibilitychange, () { if (document.hidden) { eventSource.close(); } else { connectWithRetry(/api/stream); } });还有个我踩过坑的细节close()之后服务端不一定会立刻感知到连接关闭。如果你用的是Node.js的res.write()往客户端推数据即使客户端已经关闭了TCP连接服务端可能还在傻傻地写直到下一次写操作抛出异常或者心跳失败才发现。所以服务端一定要监听连接关闭事件在回调里主动清理所有定时器和推送任务。3.4 鉴权原生EventSource的瓶颈与fetch替代方案SSE在浏览器端最让人头疼的限制之一就是EventSource不支持自定义请求头。你在new EventSource(url)的时候没法像fetch那样设置Authorization头这让很多团队在使用Token鉴权时非常痛苦。现在最常见的做法有三种。第一种把Token放在URL查询参数里const token getToken(); const eventSource new EventSource(/api/stream?token${token});这种方式最简单但有个隐患Token会出现在浏览器历史记录、访问日志、代理日志里容易泄露。而且如果服务端通过URL鉴权还要考虑Token过期后怎么续期。第二种利用Cookie做鉴权。EventSource在跨域场景下可以通过withCredentials true携带Cookie同域下默认也会带上。前提是服务端要正确配置CORS允许客户端携带凭据const eventSource new EventSource(/api/stream, { withCredentials: true });服务端CORS响应头必须具体指定来源不能随便写*同时要设置Access-Control-Allow-Credentials: true。这种方式比放在URL里安全一些但需要小心CSRF攻击服务端必须校验请求来源Origin。第三种完全绕开原生EventSource用fetch ReadableStream自己解析SSE。这种方法可以自定义请求头也能用AbortController精细控制中止是目前我推荐给需要正规鉴权场景的方案。不过代价是你要自己实现事件流解析和重连。下面是一个简化版async function createSSEWithToken(url, token, onMessage) { const response await fetch(url, { headers: { Authorization: Bearer ${token}, Accept: text/event-stream } }); if (!response.ok) { throw new Error(HTTP ${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 }); // 按空行切分事件 const chunks buffer.split(\n\n); buffer chunks.pop(); for (const chunk of chunks) { const event parseSSEChunk(chunk); if (event event.data) { onMessage(event); } } } } function parseSSEChunk(chunk) { const lines chunk.split(\n); const event { id: null, event: message, data: [] }; for (const line of lines) { if (line.startsWith(:)) continue; // 注释 const sepIndex line.indexOf(:); if (sepIndex -1) continue; const field line.slice(0, sepIndex).trim(); const value line.slice(sepIndex 1).trim(); if (field data) { event.data.push(value); } else if (field event) { event.event value; } else if (field id) { event.id value; } else if (field retry) { event.retry parseInt(value, 10); } } if (event.data.length 0) return null; event.data event.data.join(\n); return event; }这段代码的核心就是把reader.read()拿到的字节流用TextDecoder解码再按SSE协议的空行边界把消息一个个分出来。自己实现解析的好处是灵活坏处是要注意各种细节比如跨多次read的边界处理所以我用了一个buffer变量把没处理完的尾部数据暂存起来。实测下来这个方案在很多AI聊天项目中表现非常稳定。代价是需要自己处理重连否则连接一断就再也不回来了。我的做法是把这个函数封装成带重试逻辑的类重连逻辑沿用前面讲的指数退避。4. 常见问题与排查技巧实录下面是这段时间在实际项目里高频遇到的SSE问题整理成一份速查表方便你直接对照排查。现象可能原因排查思路与解决方案stream disconnected before completion: idle timeout waiting for sse代理或服务端空闲超时调大Nginx的proxy_read_timeout服务端加心跳注释检查网络链路中的代理层前端页面一片空白打开开发者工具发现SSE请求一直pendingHTTP/1.1连接数被占满检查页面有多少个EventSource实例是否组件卸载后没close改用HTTP/2或减少连接数消息收到了但事件名不触发event字段与addEventListener监听的事件名不一致抓包看原始响应确认事件名完全匹配注意大小写数据一坨一坨的延迟到达代理层缓冲了响应设置X-Accel-Buffering: no关闭Nginx缓冲检查网关是否有响应缓冲选项重连后消息重复或丢失没用Last-Event-ID做续传或服务端没发id字段每条消息都带id重连时把Last-Event-ID或自定义参数传给服务端需要带Authorization头EventSource不支持自定义请求头改用fetch ReadableStream解析SSE或用URL参数、Cookie传Token谷歌浏览器打开SSE页面闪一下变空白可能是JS报错导致渲染崩溃也可能是连接错误未被捕获打开控制台看具体报错给onerror加日志检查是否做过全局错误捕获页面切到后台一段时间后连接就断移动端或某些浏览器对后台连接做了限制监听visibilitychange回到前台时重新建立连接服务端已经关闭连接前端还在不断重连浏览器自动重连机制默认无限重试自定义重连策略限制次数用指数退避超过次数后提示用户fetch方式读取SSE出现乱码解码方式不对统一用TextDecoder(utf-8)并且使用{ stream: true }处理跨chunk的字符先展开讲一下最让我记忆深刻的一次排查。那次是客户反馈服务端日志里出现了大量“stream disconnected before completion: idle timeout waiting for sse”而且集中在某些时间段。最开始我以为是服务端超时配置的问题但调大proxy_read_timeout之后现象依然存在。后来抓了完整请求链路的日志才发现是客户在内网里套了一层企业级HTTP代理这个代理层的空闲超时只有30秒而我们的SSE业务恰恰经常出现几秒到二十几秒的静默期。虽然我们后来把心跳频率改成了10秒一次彻底解决了问题但这次经历告诉我排查这类问题时不能只盯着自己的服务端一定要沿着链路把所有代理层都过一遍。再说一个关于Chrome连接数的坑。Chrome在HTTP/1.1下对同一个域名最多只允许6个并发连接。SSE是长连接如果你在一个页面上开了三个SSE连接同时页面还在请求图片、接口、静态资源那6个连接很快就会被占满后续请求全部排队表现就是页面卡顿、图片加载不出来、接口响应特别慢。解决办法有几个方向一是减少SSE连接数量尽量把一个页面里的多条推送合并到一条SSE通道二是部署HTTP/2多路复用解决并发限制三是注意在页面销毁时及时close()掉不再需要的连接。还有一个容易被忽视的缓存问题。SSE请求如果没设置正确的缓存头某些代理甚至浏览器自身可能会把响应缓存起来导致前端拿到的不是实时的数据流而是上一次缓存的完整响应。服务端必须在响应头里设置Cache-Control: no-cache同时最好加上Connection: keep-alive。5. 我的一些实操心得写到这里这篇关于SSE在浏览器端解析、重连与中止的内容基本讲完了。最后再分享几点我在实际项目里沉淀下来的经验算是这个系列固定的收尾习惯。第一凡是做SSE服务端我一定会让每条消息都带id字段。这几乎是零成本的事情但能保证后续无论前端怎么重连、网络怎么抖动服务端都有办法做消息续传。没有id的SSE数据流一旦断线重连后客户端和服务端的状态就会出现裂缝这种问题最隐蔽排查起来也最耗时间。第二心跳不只是服务端的事前端也要有“看门狗”。具体来说我在前端会记录最后一次收到消息的时间然后开一个定时器如果超过一定阈值比如90秒没有收到任何数据就主动close()并重新建立连接。这样做能避免那种“连接看起来还挂着但实际链路已经死亡”的僵尸连接。第三无论是原生EventSource还是fetch流连接生命周期的治理一定放在统一的模块里不要散落在各个业务组件中。单独维护一个sseManager负责建连、重连、心跳监控、组件卸载时的全量清理项目大了以后收益非常明显。我见过太多项目因为SSE连接管理分散页面一多连接数直接爆炸最后只能大面积重构。SSE这个技术本身不复杂但它的细节都在边界情况和异常处理里。你只有把连接建立后会发生什么、断线后会发生什么、关闭时会发生什么这三条路径都想透了才能真正在生产环境里用得踏实。希望这篇从一个浏览器开发者的视角写的经验总结能帮你少踩几次我踩过的坑。下一篇文章我们继续往协议深处走。