最近在做一个运营后台的实时消息推送需求服务端有新的订单状态变更、告警消息需要第一时间推到浏览器页面上延迟还要控制在秒级以内。技术选型的时候我在 WebSocket 和轮询之间纠结了一阵最后落到了 JavaScript 的SSEServer-Sent Events连接上而且整个链路强制走 HTTPS。这篇文章把整个选型、实现、部署的完整过程梳理出来重点讲清楚 HTTPS 环境下 SSE 会踩到的那些坑以及最后我是怎么一个个解决的。SSE 是浏览器原生支持的服务端单向推送方案客户端用EventSource建立一条 HTTP 长连接服务端持续往这条连接里写数据帧前端监听对应事件就能实时拿到数据。相比轮询它省掉了大量无效请求相比 WebSocket它不需要协议升级、不需要额外的 ws 服务端跑在普通 HTTP 接口上就能用。特别适合通知提醒、实时大屏、后台任务进度这类只需要“服务端推、客户端收”的场景。如果你正准备在 HTTPS 站点里做类似的实时推送或者是想从轮询切换到 SSE 又怕踩坑这篇文章可以直接当一份参考笔记来用。1. 实时推送方案为什么偏偏是 SSE1.1 三种实时推送路线的对比说实话接到“服务器有变化就立刻通知页面”这个需求时第一反应其实是想用 WebSocket。但把需求掰开揉碎之后发现我要的只是单向推送页面不会往服务端发实时消息最多是请求一下历史数据。这个前提下三条路线的特点就很清楚了。第一个候选是短轮询。前端每 3 秒发一个请求问“有没有新数据”服务端不管有没有都得回一次。问题很明显90% 的请求都是空转QPS 上去了但有效信息很少而且“3 秒一次”意味着实时性上限就是 3 秒想把延迟降到 1 秒以内就得 1 秒轮一次服务器压力直接翻倍。这在量级小的时候能凑合一旦监控项多了就容易把接口打爆。第二个候选是WebSocket。双向、低延迟、可以传二进制确实很强。但代价是服务端要做协议升级要维护连接状态通常还得引入专门的库浏览器端也要处理onmessage/onclose/ 心跳 / 自动重连这一套逻辑。我这次的服务端只是个普通的 Node.js HTTP 服务为一个单向推送引入整套 WebSocket 基础设施有点杀鸡用牛刀。第三个就是SSE。它是纯 HTTP 的不需要协议升级服务端就是往res里不断写数据浏览器端一个EventSource对象就搞定了而且自带断线重连服务端还能通过Last-Event-ID帮客户端续传。唯一让我一开始不太放心的点是它在生产环境到底稳不稳尤其是叠加 HTTPS 之后有没有额外限制。1.2 SSE 在 HTTPS 链路下的优势选 HTTPS 不是为了标新立异是因为业务页面本身就在 HTTPS 下浏览器对“HTTPS 页面发起混合内容请求”管得极严如果页面是https://而EventSource指向http://的连接浏览器会直接拦截控制台报 Mixed Content 错误连接根本建立不起来。所以结论很简单HTTPS 页面必须配 HTTPS 的 SSE 端点。反过来看SSE 挂在 HTTPS 上还有一个隐性好处——代理层、负载均衡层对它没有特殊的协议识别需求它看起来就是一个普通的 GET 长请求TLS 加密之后内容完全不可见中间链路节点只会把它当普通流量转发。很多企业内网安全策略里WebSocket 的 Upgrade 请求容易被网关扫描判为异常而 SSE 这种“普通 GET 长连接”反而容易放行。提示SSE 并不是 WebSocket 的替代品。如果业务需要客户端向服务端实时发消息或者需要真正的双向低延迟那还是老老实实上 WebSocket。1.3 提前确认你的场景适不适合 SSE我这次判断场景适合用 SSE主要看三点第一数据流方向是服务端到客户端单向的第二消息频率不是毫秒级极端高频秒级或数百毫秒级就够第三客户端只需要文本数据不需要二进制帧。如果一个场景里消息量特别大每秒几百条甚至上千条或者需要客户端和服务端频繁互动SSE 就不太合适了。另外注意SSE 依赖浏览器底层连接机制在移动端 WebView 里部分版本对长连接的支持有各种小毛病如果目标用户大量在老旧 WebView 里最好先做个设备覆盖测试再定方案。2. 服务端实现Node.js 怎么把事件流“推”出去2.1 一个最小可跑的 SSE 路由我后端用的是 ExpressSSE 本质就是一路普通的 GET 接口只是响应头和响应体有特殊约定。先上最小实现// server.js const express require(express) const app express() app.get(/api/stream, (req, res) { // SSE 必需的三个响应头 res.writeHead(200, { Content-Type: text/event-stream, Cache-Control: no-cache, Connection: keep-alive }) // 先发一条注释行用来探测连接是否正常 res.write(: connected\n\n) // 模拟每 2 秒推送一条消息 const timer setInterval(() { const payload { type: order_status, orderId: Date.now(), status: SHIPPED, time: new Date().toISOString() } res.write(data: ${JSON.stringify(payload)}\n\n) }, 2000) // 客户端断开时清理定时器 req.on(close, () { clearInterval(timer) res.end() }) }) app.listen(3000, () console.log(SSE server on :3000))text/event-stream是 SSE 的 MIME 类型这是服务端和浏览器之间心照不宣的约定。响应头里Cache-Control: no-cache是为了禁止任何中间层缓存这个流式响应不然浏览器可能拿到一份“腌过”的数据。Connection: keep-alive则是告诉链路别随手掐断这条长连接。事件流的格式核心是data:前缀加一行 JSON然后是两个换行符\n\n作为一条消息的结束标记。很多第一次写的人容易只写一个\n结果浏览器把两条数据黏在一起解析JSON.parse 直接报错。2.2 心跳和重连参数连接保活的底层逻辑长连接最怕的不是断而是“不知不觉被掐掉”。云厂商的负载均衡、Nginx 的proxy_read_timeout、容器网络里的 idle 连接回收都会在一定静默时间后主动断开连接。这个时间通常是 60 秒到 5 分钟不等。解决办法就是心跳。SSE 协议里有一种特殊注释行以:开头格式类似: ping浏览器收到会直接忽略但连接上有数据流过就能让中间层的 idle 超时永远不会被触发。// 每 15 秒发一条注释行保活连接 const heartbeat setInterval(() { res.write(: ping\n\n) }, 15000)我实测下来心跳间隔设在 15 秒比较稳。设太短比如 5 秒会让服务端产生额外的定时器压力设太长比如 60 秒则可能在网关 60 秒超时边缘反复横跳只要有一次调度抖动就会断线。15 到 30 秒是一个安全区间。另外浏览器默认在连接断开后 3 秒重连这个值也可以由服务端指定在数据流里写一个retry:字段res.write(retry: 5000\n\n)这样浏览器收到后以后每次重连的间隔都会按 5 秒执行适合服务端明显过载的场景让客户端别像打了鸡血一样重连。2.3 HTTPS 环境下服务端要额外注意的一件事服务端在 HTTPS 后面最常见的问题不是 TLS 本身而是代理层缓冲。Nginx 默认开了proxy_buffering它会把上游返回的数据攒到一定大小再发给客户端这对普通接口没问题但对 SSE 是致命的——你 2 秒推一条数据客户端可能 30 秒后才看到一批。这问题非常隐蔽因为浏览器连接受影响直接在服务端 curl 却是秒回的现象就是“服务端明明在推前端就是不来数据”。解决方法是关闭缓冲并告诉 Nginx 这个响应不要缓冲。除了在 Nginx 配置里加指令第 4 节会写也可以在服务端响应头里加一个X-Accel-Buffering: noNginx 会认这个头。我两个地方都做了双保险。3. 前端 JavaScript 接入EventSource 的正确用法3.1 一分钟建立连接前端接入非常简单核心代码就这么几句const source new EventSource(/api/stream) source.onopen () { console.log(SSE 连接已建立) } source.onmessage (event) { const data JSON.parse(event.data) updateOrderStatus(data) } source.onerror (err) { console.warn(SSE 连接异常浏览器会自动重连) }new EventSource(url)会发起一个普通 GET 请求成功后长连接就挂上了。浏览器原生支持自动重连onerror里不需要手动去 new 一个新的 EventSource让浏览器默认行为接管就行。如果在这里去手动重建容易造成重连风暴——多个连接实例互相竞争服务端同时挂着好几个来自同一页面的连接。3.2 自定义事件与命名空间需要区分不同类型的消息比如订单状态和告警消息不混在一起处理用自定义事件比在data里用字段打标更干净。服务端可以在事件流里写event:字段res.write(event: order_status\n) res.write(data: ${JSON.stringify(orderData)}\n\n) res.write(event: alert\n) res.write(data: ${JSON.stringify(alertData)}\n\n)前端对应的监听方式source.addEventListener(order_status, (event) { const order JSON.parse(event.data) // 处理订单状态 }) source.addEventListener(alert, (event) { const alert JSON.parse(event.data) // 弹告警 })这种做法的好处是前端可以针对事件类型做独立的错误处理也不会因为某个数据格式变动影响所有监听逻辑。服务端没有明确指定event:的消息会落在默认的onmessage上这条规则容易踩最好在团队里约定清楚要么所有推送都带event:要么都不带混用会导致前端逻辑混乱。3.3 断线重连与 Last-Event-ID消息到底丢没丢用 SSE 最关心的一个问题是断线期间的消息会不会丢浏览器原生重连确实能解决连接恢复但恢复后服务端该从哪里继续推协议标准给了答案Last-Event-ID。服务端推送时给每条消息一个id:浏览器会自动记住收到的最后一条 ID重连时作为Last-Event-ID请求头发给服务端。服务端看到这个头就能从断点之后继续推。服务端补全let eventId 0 const pushEvent (event, data) { res.write(id: ${eventId}\n) res.write(event: ${event}\n) res.write(data: ${JSON.stringify(data)}\n\n) }前端不需要任何额外代码浏览器拿到了Last-Event-ID后会存在内部重连时自动带上// 接住重连后的 EventSource 请求头 app.get(/api/stream, (req, res) { const lastEventId req.headers[last-event-id] if (lastEventId) { // 从缓存或消息队列里定位断点把断点后的消息补推 const messages getMessagesAfter(lastEventId) messages.forEach((msg) pushEvent(msg.event, msg.data)) } })这里有个我自己踩过的坑req.headers[last-event-id]是字符串如果服务端用自增整数做 ID断点定位时一定要转成Number再比较否则9 10这种字符串比较会让你拿到一堆重复消息。3.4 页面生命周期管理不清理会泄漏SSE 连接挂在页面上页面关闭浏览器会自动断掉。但单页应用里组件切换、路由跳转时不会关闭页面如果只new EventSource而不close旧连接会一直挂着一个单页应用开个十几次路由跳转浏览器里可能囤了十几个到同一个端点的连接。正确姿势是在组件销毁或路由离开时主动关掉let source function startStream() { source new EventSource(/api/stream) source.onmessage handleMessage } function stopStream() { if (source) { source.close() source null } }我还加了visibilitychange的监听页面切到后台标签页时实时推送的优先级其实没那么高我选择在页面隐藏时close()等到页面重新可见再重新建立连接。配合Last-Event-ID回来之后消息可以续上。这样既省了连接资源又不需要为后台页重新渲染操心。4. 穿透 HTTPS 的部署层问题Nginx 与网关配置4.1 Nginx 反代 SSE 的两个关键开关项目上线用的是 Nginx 做 HTTPS 终结SSL 证书配置这里不展开重点说反代 SSE 的两个必须开的开关。一个典型配置长这样location /api/stream { proxy_pass http://backend:3000; proxy_http_version 1.1; proxy_set_header Connection ; proxy_buffering off; proxy_cache off; proxy_read_timeout 3600s; proxy_send_timeout 3600s; }逐个解释proxy_http_version 1.1proxy_set_header Connection HTTP/1.1 默认是 keep-alive 的但如果上一跳带了Connection: keep-aliveNginx 可能会做特殊处理。对 SSE 场景直接把 Connection 头清空让 Nginx 和上游保持长连接同时不对 SSE 响应做什么附加的 chunked 处理。proxy_buffering offSSE 的命根子。不关的话Nginx 会把事件流缓冲起来前端拿到的是延迟后的批量数据实时性完全废掉。proxy_cache off严禁任何缓存层碰这个端点响应的流式数据一旦被缓存轻则数据延迟重则整个连接直接异常。proxy_read_timeout 3600sNginx 默认proxy_read_timeout只有 60 秒上游在这个时间内不传数据Nginx 就会掐断连接。虽然有 15 秒一次的心跳在但把超时时间拉长是为了兜底心跳机制万一出问题时不至于 60 秒就断。4.2 网关与负载均衡的 idle 超时公司内部链路如果还叠了网关层比如云负载均衡、API 网关它们的 idle 超时策略五花八门有的 30 秒就回收空闲连接。就算你 Nginx 配了 3600 秒前置 LB 30 秒把一个“看起来没数据”的连接回收了照样断。排查方法很直接用curl -N直接打到源站、打到 Nginx、打到 LB分别看哪一层会断curl -N https://yourdomain/api/stream在终端里观察连接是否能持续输出。如果源站没问题、Nginx 有问题查proxy_read_timeout如果 Nginx 没问题、经过 LB 就断大概率是 LB 的 idle 超时这时候只能把心跳间隔缩短到 LB 超时时间的一半以下或者申请对这条路径放宽 idle 限制。4.3 本地开发自签名 HTTPS 和 EventSource 的坑本地开发时后端也模拟 HTTPS换来换去证书又容易折腾我直接用了自签名证书。这里有个容易踩的点浏览器访问自签名 HTTPS 站点时如果只是“高级 - 继续前往”绕过了一次EventSource请求依然会被拦截。我的经验是本地开发最好用一个本机信任的证书工具把证书安装到系统信任链这样浏览器地址栏不再有警告EventSource才能正常建立。如果实在懒得装证书开发环境可以把页面和EventSource的地址都保持在 HTTP只有生产环境走 HTTPS注意代码里不要写死协议用相对路径new EventSource(/api/stream)让它跟着页面协议走这样可以少踩一个混合内容的大坑。5. 跨域、认证与连接数限制5.1 跨域部署时的 CORS 配置如果 SSE 端点和页面不在同一个域浏览器同样遵循同源策略跨域请求需要 CORS 头配合。后端要加这样一组响应头res.writeHead(200, { Content-Type: text/event-stream, Cache-Control: no-cache, Access-Control-Allow-Origin: https://admin.example.com, Access-Control-Allow-Credentials: true, Access-Control-Allow-Headers: Last-Event-ID })Access-Control-Allow-Origin必须明确指定具体的源不能随手写成*尤其是当你后面要用到withCredentials时Allow-Origin: *和凭证模式是冲突的浏览器会直接拒绝响应。跨域场景下EventSource的Last-Event-ID请求头属于自定义请求头需要在预检请求里允许对应到上面的Access-Control-Allow-Headers。前端跨域连接时带上withCredentials才能携带 Cookieconst source new EventSource(https://push.example.com/api/stream, { withCredentials: true })5.2 EventSource 不支持自定义 Header认证方案要绕路有次想给接口加个Authorization: Bearer xxx头翻了一圈文档才意识到浏览器原生的EventSource不支持自定义请求头。new EventSource(url, { headers: { ... } })在浏览器里面根本不生效它在规范里就没有这个选项。实际可用方案有三个Cookie 认证。让用户先登录拿 CookieEventSource请求自然带上 Cookie服务端从会话里解析身份。这是最简单、也最受支持的做法但前提是 SSE 端点和登录系统同域或者跨域支持withCredentials。Token 放在 URL query 上。比如new EventSource(/api/stream?tokenabc123)服务端校验 query 参数。简单直接坏处是 token 会出现在访问日志、代理日志里有泄露风险一般要配合短时效 token 使用。通过子域避免跨域。把推送域名放在主域的子域下配合 Cookie 的 Domain 属性既不用写 CORS也能带上身份凭证。我项目里选的是方案 2 短时效 token因为内部系统对多个服务端用独立 token 更灵活。如果你要对接第三方提前和对方确认清楚用哪种认证方式否则联调时会发现“明明接口要认证我 EventSource 却带不了认证头”这种尴尬局面。5.3 浏览器同域连接数限制与 HTTP/2还有一个低调的坑浏览器对同一个域名的HTTP/1.1 连接数是有限制的一般是 6 个。如果你的页面同时开了多个EventSource到同一个域名再叠加一些普通接口请求第 7 个请求会一直排队表现就是连接卡住不动、迟迟没有数据。遇到这种场景解决思路有三条尽量收敛到一个推送端点前端用一个 EventSource 接收所有事件类型就是第 3 节讲的自定义事件不要为一个业务模块开一个连接如果确实要开多个流把不同流拆到不同子域名比如push1.example.com、push2.example.com各自的 6 连接配额独立让整个站点走HTTP/2。HTTP/2 的多路复用不占连接数名额EventSource在 HTTP/2 下可以开很多路而不撞连接数上限。现在 HTTPS 站点基本都是 HTTP/2如果你的 Nginx 或 CDN 还没开值得优先打开。6. 常见问题与排查技巧实录6.1 连接秒断、前端一直在重连这种几乎可以锁定是两件事之一要么是服务端异常中断要么是代理层拒绝长连接。先在服务端日志里看req.on(close)是否有大量触发如果每次连接建立后几秒就被关闭用 curl 逐层试curl -v -N http://127.0.0.1:3000/api/stream # 源站 curl -v -N https://yourdomain/api/stream # 完整链路如果源站正常、域名不行重点查 Nginx 错误日志和 LB 配置。另外一个隐蔽原因是上游的 HTTP 版本不匹配比如 Nginx 和上游之间用了proxy_http_version 1.0就没有 keep-alive 语义连接会频繁重建。6.2 数据卡在某个时间点不再推送连接没断页面也还开着但消息就是不来了。这类问题的首要嫌疑是Nginx buffering 没关或者中间某层加了缓存。数据流被攒在缓冲区满了一定大小才吐给客户端表现形式就是“很久才跳一大段数据”。还有一个嫌疑是服务端定时器提前被清理。我某次在req.on(close)里把心跳定时器和推送定时器一起clearInterval了结果有一批客户端是正常断开的之后我重启了服务但旧客户端的连接在服务端看来还是活的实际上已经不会收到任何新数据。排查时只要打开浏览器 Network 面板点击那条 EventStream 类型的请求看是不是一直有数据帧就能判断卡在哪一端。6.3 前端重复收到旧数据重连之后重复消息多半出在Last-Event-ID的处理上。服务端如果没有正确解析这个头或者解析成了字符串比较就会把断点之前的数据又推一遍。解决办法是把断点定位做实同时让前端消费消息的业务逻辑具备幂等性也就是即使收到重复消息也不会产生副作用比如只更新 UI 状态不重复提交统计。我后来在推送数据里额外加了一个msgId字段前端用 Map 记录最近处理过的msgId重复的不再处理双保险。像订单状态这类业务消息依赖幂等消费是基本功。6.4 速查表SSE HTTPS 排查清单现象优先排查项做法连接一直重连代理层超时 / 服务端未发送正确头关闭缓冲加心跳拉长proxy_read_timeout数据延迟批量出现Nginxproxy_buffering未关配置proxy_buffering off加X-Accel-Buffering: noHTTPS 页面 EventSource 失败混合内容拦截确保事件流端点也是 HTTPS代码用相对路径跨域被浏览器拦截CORS 配置不完整显式设置Allow-Origin跨域认证用withCredentials断线重连后重复消息Last-Event-ID未生效服务端读取请求头业务消费做幂等一个页面开了多个连接不推送同域连接数超限合并为一个端点或切换 HTTP/2用curl -N是验证整个链路最趁手的工具建议从一开始就习惯它。每次改动代理层或服务端之后先用 curl 确认事件流不断再去打开页面看浏览器表现能省下很多无头绪的定位时间。最后再分享一个小技巧我之前在服务端用了一个简单的内存订阅器模拟消息中心生产环境换成了内部的消息中间件SSE 服务端只是把消息桥接到浏览器端。这个切换过程中踩得最狠的一次坑是忘记在连接关闭时把订阅监听器解绑导致内存里积了大量已断开连接的引用。后来统一在close事件里做“清理定时器 解绑监听器 断掉响应”三步才算彻底稳下来。如果你也要做类似的消息桥接一开始就把连接的生命周期管理写清楚后面会省很多事。