Beego实现大文件下载必须绕过Output层直写ResponseWriter，用io.Copy流式传输并手动设置Content-Length、Content-Disposition（中文名需url.PathEscape）、Content-Type等响应头，严禁使用Download()或WriteString()以防OOM。
Beego 没有像 Gin 那样的 c.DataFromReader() 专用流式响应方法，但完全能实现大文件安全下载和分块读取——关键不是找“对应 API”，而是绕过框架封装、直接操作 http.ResponseWriter 并配合标准库流式接口。
为什么不能用 beego.Controller.Ctx.Output.Download() 或 WriteString()
这两个方法本质是把文件内容先读进内存再写出去：Download() 内部调用 os.ReadFile()，WriteString() 要求传入完整字符串。1GB 文件会直接触发 runtime: out of memory panic，不是慢，是崩。Beego 的 Output 模块设计目标是小响应体（HTML、JSON、短文本），不承载流式语义。
正确做法：跳过 Output 层，直写 ResponseWriter
必须放弃 c.Ctx.Output.* 系列方法，改用 c.Ctx.ResponseWriter（即原生 http.ResponseWriter）配合 io.Copy 或 io.CopyBuffer。操作前需手动设置全部响应头，且顺序不能错：
-
Content-Length必须设为真实字节数（stat.Size()），否则浏览器无法显示进度条，CDN 可能拒绝缓存 -
Content-Disposition中文文件名必须用url.PathEscape()编码，且格式为filename="xxx"（不是filename*=），否则前端Blob接收时乱码 -
Content-Type不能填"application/octet-stream"，要按实际类型设，如"application/zip"、"video/mp4" - 所有
Header().Set()必须在第一次Write()前完成，否则 panic
示例片段：
f, err := os.Open("/data/reports/monthly.zip")
if err != nil {
c.Ctx.Abort(404)
return
}
defer f.Close()
stat, _ := f.Stat()
c.Ctx.ResponseWriter.Header().Set("Content-Length", fmt.Sprintf("%d", stat.Size()))
c.Ctx.ResponseWriter.Header().Set("Content-Disposition", `attachment; filename="`+url.PathEscape("月度报告.zip")+`"`)
c.Ctx.ResponseWriter.Header().Set("Content-Type", "application/zip")
_, err = io.Copy(c.Ctx.ResponseWriter, f)
if err != nil && err != http.ErrHandlerTimeout {
// 注意：broken pipe、client disconnect 会在这里返回，不应 panic
}
需要自定义 chunk size 或加解密？用 io.LimitReader + io.CopyN
当你要控制每次读 512KB、插入哈希计算、或对接加密流时，io.Copy 的黑盒缓冲不可控。此时应组合 io.LimitReader 和 io.CopyN：
-
io.LimitReader(f, 512*1024)返回一个只读前 512KB 的新io.Reader，不移动原始*os.File的 offset -
io.CopyN(dst, limitedReader, 512*1024)确保最多复制 512KB，并返回实际字节数，遇到 EOF 时n < 512*1024是正常现象 - 不要用
ReadFull：它要求必须读满，大文件末尾块不满就报io.ErrUnexpectedEOF，这不是错误 - 缓冲区大小建议 32KB–1MB；小于 32KB syscall 过多，大于 1MB 在 NFS 或慢网关上反而卡住
分块读取后写入另一个文件？别用 os.O_APPEND
并发写或精确控制偏移时，os.O_APPEND 是陷阱：它每次 Write 前强制 seek 到 EOF，彻底破坏 chunk 边界对齐。正确方式取决于场景：
- 单 goroutine 顺序写：用
os.O_CREATE | os.O_WRONLY | os.O_TRUNC，先清空再写，避免残留 - 多 goroutine 写不同偏移：用
os.O_CREATE | os.O_WRONLY+file.WriteAt(buf, offset)，确保 offset 不重叠 - 写入前务必检查
err，尤其是write: broken pipe或no space left on device—— 流式处理中这类错误常静默发生于某一块之后
真正难的从来不是“怎么读完”，而是 offset 记录、断点恢复、加密块对齐这些边界逻辑——它们不在 Beego 文档里，但在生产环境里天天出问题。
