必须手动设置text/event-stream响应头且在首次写入前调用WriteHeader(),显式flush事件并断言Flusher接口,禁用gzip等缓冲中间件,添加心跳保活防止代理断连。

必须手动设置 text/event-stream 响应头,且不能晚于第一次写入
Echo 默认不会提前发送响应头,而 EventSource 客户端在收到完整 200 OK 响应头前会一直卡在 connecting 状态。如果你用 c.String() 或 c.JSON(),它们会在写完内容后才调用 WriteHeader(),此时连接已关闭,SSE 失效。
正确做法是:在 handler 开头就显式调用 c.Response().Writer.WriteHeader(http.StatusOK),再设置 header:
c.Response().Writer.WriteHeader(http.StatusOK)
c.Header("Content-Type", "text/event-stream")
c.Header("Cache-Control", "no-cache")
c.Header("Connection", "keep-alive")
注意:c.Header() 必须在 WriteHeader() 之后调用,否则某些中间件(如 CORS)可能覆盖掉 Content-Type;gzip 中间件也必须跳过该路由,否则压缩会破坏流格式。
每条事件后必须显式 f.Flush(),不能依赖 handler 结束自动刷
SSE 要求每个事件块(data: ...\n\n)写入后立刻送达客户端,否则浏览器收不到任何数据。Echo 的 c.Response().Writer 是个 http.ResponseWriter 接口,底层不一定支持 Flush(),必须先断言:
rw := c.Response().Writer-
f, ok := rw.(http.Flusher);若!ok,说明当前环境(如测试 wrapper、某些代理中间件)不支持流式刷新,应直接返回错误 - 每次写完一个事件后,立即调用
f.Flush(),并检查错误:if err != nil && !errors.Is(err, net.ErrClosed) && !errors.Is(err, syscall.EPIPE)—— 其他错误需记录并退出循环 - 别用
defer f.Flush(),那只是 handler 返回时刷一次,毫无意义
禁用 gzip 和缓冲中间件,否则响应体被截断或延迟
默认启用的 middleware.Gzip() 会包装 writer,导致 Flush() 失效或内容被缓存;同理,自定义缓冲中间件(如日志、body read)也可能拦截流式输出。
推荐两种处理方式:
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景,三层路由架构(触发词→SAD反馈→DAG编排),recall@10=96.97%。配置驱动(chains.yaml),零代码扩展。pip install skill-weave-chains 一键安装。
- 全局禁用 gzip:在
e.Use(middleware.GzipWithConfig(...))中用Skipper匹配Accept头含text/event-stream的请求 - 路由级跳过:对 SSE handler 不调用
e.Use(...),或用e.Group()隔离,单独注册无缓冲中间件
另外,确保没启用 middleware.Recover() 以外的、会读取 request body 的中间件(如 Bind()),它们可能阻塞连接。
必须加心跳保活,否则 Nginx/ALB 在 60 秒后主动断连
反向代理(Nginx、ALB、Cloudflare)默认空闲超时为 60 秒,而 SSE 允许长时间静默。仅靠 retry: 字段无法防止断连,它只控制重连间隔。
服务端需每 15–30 秒发一次注释行心跳:
fmt.Fprintf(rw, ":\n\n") f.Flush()
同时,事件循环中不能只监听 c.Request().Context().Done() —— TCP FIN 在代理后可能延迟数秒才到达,goroutine 易泄漏。应使用 select 同时监听:
-
ctx.Done()(请求取消) - 下游数据 channel(业务事件源)
- 心跳
time.Ticker(如time.NewTicker(20 * time.Second))
任一触发即清理资源、退出循环。
最常被忽略的是 flush 断言和代理心跳——前者让整个流“哑火”,后者让连接在生产环境随机中断,现象都是前端卡在 connecting,但控制台无报错。这两处不处理,SSE 在 Echo 下基本跑不通。


















