大文件下载需流式处理避免OOM：用ResponseWriter分块传输、手动支持Range断点续传、RFC5987规范设置中文文件名、限制请求超时、禁用gzip、避免高频日志。
大文件下载时内存暴涨甚至 OOM
直接用 echo.Context.File() 或 echo.Context.Stream() 返回超大文件（如 >500MB），会把整个文件读进内存再发给客户端，Go 进程 RSS 瞬间飙升，容易触发 Kubernetes OOMKilled 或本地 panic。
根本原因是默认行为调用了 io.ReadAll() 类似逻辑，没做流式控制。必须绕过框架的「全量缓冲」路径，自己接管底层 http.ResponseWriter 的写入过程。
- 用
ctx.Response().Writer获取原始http.ResponseWriter，避免 Echo 封装层二次缓冲 - 打开文件后立即调用
file.Stat()获取大小，设置Content-Length头（否则浏览器无法显示进度） - 使用带缓冲的
bufio.Writer包裹响应体，但缓冲区别设太大（4096足够，64KB反而增加延迟） - 用
io.CopyBuffer()配合固定大小的 byte slice（如make([]byte, 32*1024)）分块传输，不依赖io.Copy()内部分配
断点续传支持（Range 请求）没生效
Echo 默认不处理 Range 请求头，ctx.File() 直接返回 200 + 全文件，客户端暂停再续就会从头下 —— 用户感知就是“下载卡住后重试变慢”。要支持断点，必须手动解析 Range 并返回 206 Partial Content。
- 检查请求头：
range := ctx.Request().Header.Get("Range")，为空则走完整下载流程 - 用
http.ParseRange()解析，它能正确处理bytes=0-、bytes=100-199、bytes=-500等格式 - 调用
file.Seek()跳转到起始偏移，用io.CopyN()或循环Read()发送指定长度，别用io.Copy()无界复制 - 务必设置
Content-Range和Accept-Ranges: bytes头，否则客户端不认为服务端支持续传
文件名中文乱码或 Safari 下载失败
Content-Disposition: attachment; filename="报告.pdf" 在 Chrome 没问题，但 Safari / Firefox 会把中文当乱码，甚至拒绝下载；某些安卓 WebView 直接报 500。问题出在 RFC 5987 规范未被严格遵循。
Echo框架 5.1.0 版本源码包下载，适合关注 RealIP 行为变化、StartConfig.Listener、NewDefaultFS 和观测性中间件入口的开发团队。
立即学习“go语言免费学习笔记（深入）”；
- 不要拼接原始中文名到
filename=后面 —— 这是最大误区 - 用
url.PathEscape()编码文件名，再套上filename*=UTF-8''{encoded}格式（注意两个单引号） - 同时保留兼容性：
filename="{fallback}"放 ASCII 字符串（如report.pdf），供老客户端 fallback - 完整头示例：
attachment; filename="report.pdf"; filename*=UTF-8''%E6%8A%A5%E5%91%8A.pdf
并发下载压测时连接数激增、超时增多
大文件传输耗时长，若每个请求都占着一个 goroutine 和 TCP 连接，100 个并发下载可能打满服务器 net.Conn 数或反向代理（如 Nginx）的 upstream timeout。
- Echo 默认不干预连接生命周期，需在 handler 开头加
ctx.SetRequestTimeout()或用中间件限制单请求最长存活时间（如10 * time.Minute） - 对超大文件（>2GB），考虑用
Sendfile系统调用（Linux）：Echo 不直接支持，但可强制转换ResponseWriter为io.WriterTo接口并调用file.(io.WriterTo).WriteTo()，由内核零拷贝发送 - 务必关闭
gzip中间件（如果启用了），压缩大文件不仅没收益，还会吃光 CPU 并阻塞 goroutine
最易被忽略的是日志 —— 别在下载 handler 里打 ctx.Logger().Info("start download") 这种行，每秒千级下载时日志 I/O 成瓶颈。真要追踪，只记录失败 case 或用结构化指标上报。
