Echo文件下载需按场景选方法:File()最简但有路径遍历风险;Attachment()支持中文文件名;大文件用Stream()避免OOM;内存生成文件用Blob();核心是路径校验、编码处理、流控和错误恢复。

Context.File() 直接发送文件但要注意路径安全
Context.File() 是 Echo 中最简捷的文件下载方式,它会自动设置 Content-Disposition: attachment 响应头,并读取本地文件流直接返回。但它的参数是**文件系统绝对路径或相对于当前工作目录的相对路径**,如果用户可控路径(比如从 URL query 传入 filename=../../etc/passwd),就会触发路径遍历漏洞。
实操建议:
- 永远不要将未经校验的用户输入拼接到路径中,例如
c.File("/uploads/" + c.QueryParam("f"))是危险的 - 若必须支持动态文件名,先用
filepath.Join()拼接,再用filepath.EvalSymlinks()和strings.HasPrefix()校验最终路径是否落在白名单目录内 - 注意:Echo v4.10+ 的
File()不会自动处理中文文件名,需手动设置Content-Disposition头(见下一条)
Context.Attachment() 更适合带中文名的下载
Context.Attachment() 和 File() 行为类似,但多一个 filename 参数,用于指定浏览器保存时显示的文件名。它内部会调用 mime.FormatMediaType() 对文件名做 RFC 5987 编码,能正确处理中文、空格等字符。
常见错误现象:
- 用
File()下载报告2024.xlsx,Chrome 显示成%E6%8A%A5%E5%91%8A2024.xlsx - 用
Attachment()时传了绝对路径(如/var/data/abc.pdf),结果报错open /var/data/abc.pdf: no such file or directory—— 实际是路径权限或工作目录不对,不是函数问题
使用示例:
func downloadHandler(c echo.Context) error {
filename := "用户数据导出.csv"
filepath := "/srv/export/user_export_123.csv"
return c.Attachment(filepath, filename)
}
大文件下载要用 Context.Stream() 避免内存暴涨
当文件体积超过几十 MB,File() 或 Attachment() 会把整个文件读进内存再写入响应体,容易触发 OOM。此时应该用 Context.Stream() 手动控制流式传输。
Echo框架 5.1.0 版本源码包下载,适合关注 RealIP 行为变化、StartConfig.Listener、NewDefaultFS 和观测性中间件入口的开发团队。
关键点:
-
Stream()接收一个func(w io.Writer) error,你需要在里面打开文件、分块io.CopyN()或bufio.Reader.Read(),并及时close() - 必须手动设置
Content-Length(可先os.Stat()获取大小)和Content-Disposition - 别忘了设
Content-Type,否则浏览器可能无法识别文件类型;对未知类型可用mime.TypeByExtension()
性能影响:流式传输内存占用恒定(约几 KB),但响应头需提前确定,不支持断点续传(如需,得自己解析 Range 头并配合 http.StatusPartialContent)
Context.Blob() 适合内存中生成的文件(如 Excel 导出)
如果文件内容来自内存(比如用 excelize 生成的 *xlsx.File),不需要落地到磁盘,就该用 Context.Blob()。它接受 contentType、contentLength 和 []byte 数据,直接写入响应体。
容易踩的坑:
- 误传指针或未
.Close()的 buffer,导致Blob()写入的是空内容或 panic - 忘记计算真实字节长度,填了
-1或错误值,浏览器可能无法识别下载完成 - 中文文件名仍需搭配
Content-Disposition头,Blob()本身不处理文件名
示例(导出 Excel):
f := excelize.NewFile() // ... 写入数据 buf, _ := f.WriteToBuffer() c.Response().Header().Set(echo.HeaderContentDisposition, `attachment; filename*=UTF-8''%E5%AF%BC%E5%87%BA.xlsx`) return c.Blob(http.StatusOK, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", buf.Bytes())
真正麻烦的从来不是选哪个方法,而是路径校验、编码处理、流控和错误恢复这四件事——漏掉任何一个,上线后都可能变成半夜告警。

















