Context.Write() 不能直接用于 SSE,必须手动设置响应头、获取 http.Flusher 并显式 Flush;需捕获写入错误处理客户端断开,禁用超时并避免不兼容中间件。

Context.Write() 不能直接用于 SSE
直接调用 ctx.Write() 或 ctx.String() 发送 SSE 消息会失败,因为 SSE 要求响应头必须包含 Content-Type: text/event-stream,且响应体需按特定格式(data: ...\n\n)持续流式输出,而 Echo 默认的响应机制会自动结束连接、关闭写入流,甚至缓冲输出——这会导致事件卡住或连接被提前关闭。
正确做法是手动接管响应体写入,并保持连接打开:
- 先调用
ctx.Response().Header().Set("Content-Type", "text/event-stream") - 再调用
ctx.Response().Header().Set("Cache-Control", "no-cache")(避免代理或浏览器缓存阻断流) - 设置
ctx.Response().Flusher()并确认其可用(部分测试环境如 httptest 不支持) - 禁用 Echo 默认的响应终止逻辑:不要调用任何
ctx.JSON()、ctx.String()等终结方法
必须用 ctx.Response().Writer 和 http.Flusher 推送事件
Echo 的 Context 封装了标准 http.ResponseWriter,但 SSE 依赖底层 http.Flusher 实时刷出数据。Echo 不提供专用 SSE 方法,所以得自己取 writer 并断言为 http.Flusher:
w := ctx.Response().Writer
f, ok := w.(http.Flusher)
if !ok {
ctx.String(http.StatusInternalServerError, "SSE not supported")
return
}
每次写入后必须显式调用 f.Flush(),否则数据滞留在缓冲区;同时建议在写入前加 ctx.Response().WriteHeader(http.StatusOK)(仅首次),避免某些客户端等待状态码才开始解析流。
常见错误:漏掉 Flush(),或在循环中反复调用 WriteHeader()(会 panic)。
Echo框架 5.1.0 版本源码包下载,适合关注 RealIP 行为变化、StartConfig.Listener、NewDefaultFS 和观测性中间件入口的开发团队。
如何安全地维持长连接并处理客户端断开
SSE 连接本质是长期存活的 HTTP 请求,但客户端可能随时关闭,服务端若继续写入会触发 write: broken pipe 或 i/o timeout 错误。Echo 的 Context 提供 ctx.IsAborted() 和 ctx.Request().Context().Done(),但更可靠的是捕获写入错误:
- 每次
w.Write()后检查返回的err,若为io.ErrClosedPipe、net.ErrClosed或http.ErrHandlerTimeout,应立即 break 循环并 return - 避免无休止 for-select 循环,建议搭配
time.Ticker或消息通道,并在 select 中监听ctx.Request().Context().Done() - 注意 Echo 默认的 ReadTimeout / WriteTimeout 会影响 SSE,需在启动时显式设为 0 或足够大值:
e.Server.ReadTimeout = 0
完整可运行的 SSE 示例结构
一个最小可行 SSE handler 长这样(省略错误日志):
func sseHandler(c echo.Context) error {
// 设置响应头
c.Response().Header().Set("Content-Type", "text/event-stream")
c.Response().Header().Set("Cache-Control", "no-cache")
c.Response().Header().Set("Connection", "keep-alive")
<pre class="brush:php;toolbar:false;">// 获取可刷新的 writer
w := c.Response().Writer
f, ok := w.(http.Flusher)
if !ok {
return echo.NewHTTPError(http.StatusInternalServerError, "streaming unsupported")
}
// 发送初始响应(避免某些客户端挂起)
c.Response().WriteHeader(http.StatusOK)
f.Flush()
ticker := time.NewTicker(2 * time.Second)
defer ticker.Stop()
for {
select {
case <-ticker.C:
_, err := w.Write([]byte("data: {"message":"tick"}\n\n"))
if err != nil {
return nil // 客户端已断开,静默退出
}
f.Flush()
case <-c.Request().Context().Done():
return nil
}
}}
注册方式:e.GET("/events", sseHandler)。注意:该 handler 不能被任何中间件包裹(如 Logger、Recover),除非中间件明确支持流式响应,否则可能提前消费或关闭 writer。
真实项目中,事件通常来自 channel 或 pub/sub 系统,此时要特别注意 goroutine 泄漏和 channel 关闭判断——ctx.Request().Context() 是唯一可信的生命周期信号。

















