c.Blob是Echo框架处理二进制响应最直接安全的方式,用于返回图片、PDF、Excel等非文本资源;必须用它而非c.String或c.JSON的场景是返回原始二进制数据,因其避免UTF-8编码破坏、不触发JSON序列化、不手动拼Header,且需准确设置contentType和完整[]byte。

c.Blob 是 Echo 处理二进制响应最直接、最安全的方式,不用自己拼 Header、不绕过框架流控、不触发 JSON 序列化。它底层调用 http.ResponseWriter.Write,原样透传字节流,适合返回图片、PDF、Excel 等非文本资源。
什么时候必须用 c.Blob 而不是 c.String 或 c.JSON
当你返回的是原始二进制(比如从 MySQL MEDIUMBLOB 字段读出的图片字节、go:embed 内嵌的 logo.png、或第三方 API 下载回来的 QR Code 二进制流),就不能走文本路径:
-
c.String会强制 UTF-8 编码,破坏二进制完整性(比如 JPG 的0xFFD8可能被转义) -
c.JSON会尝试序列化,对[]byte默认转成 Base64 字符串,前端还得再解码,多一层损耗 - 手动用
c.Response().Write容易漏设Content-Type或忘记WriteHeader,浏览器无法正确识别类型
c.Blob 的三个参数怎么填才不出错
函数签名是 c.Blob(code int, contentType string, b []byte) error,关键在后两个参数:
Echo框架 5.1.0 版本源码包下载,适合关注 RealIP 行为变化、StartConfig.Listener、NewDefaultFS 和观测性中间件入口的开发团队。
-
contentType必须准确:图片用"image/jpeg"、"image/png";PDF 用"application/pdf";不要写成"image/jpg"(无效 MIME)或空字符串 -
b必须是完整、未损坏的[]byte:从数据库查 BLOB 后别做任何string(b)转换;用io.ReadAll读 HTTP 响应体时确保没截断 - 状态码推荐用
http.StatusOK(200),除非你要表达临时重定向(302)或错误(404/500)
常见坑:MySQL BLOB 回显时图片裂开或显示下载框
这不是 c.Blob 的问题,而是上下文缺失导致的典型表现:
- 没设
Content-Disposition:浏览器看到image/*类型但没指定是否内联,可能默认触发下载。加一行c.Response().Header().Set("Content-Disposition", "inline")强制内联显示 - 数据库字段查出来是
nil或空 slice:没做if len(data) == 0判断,直接传空[]byte给c.Blob,返回空白响应 - 前端请求带了
Accept: application/json,后端却硬返回图片:浏览器可能忽略二进制内容。确保 URL 路径语义清晰(如/api/image/:id),避免和 JSON 接口混用同一路由
真正要小心的,是 contentType 和原始字节的匹配关系——哪怕一个字符错,浏览器就放弃渲染。其他所有封装(比如 Base64 转换、流式分块)都是可选优化,而这两项是底线。
















