http.ServeFile适用于可信固定路径的静态文件下载，自动处理Range请求和Content-Disposition，但存在目录遍历风险；自定义下载需手动设Content-Type与Content-Disposition（中文名用filename*=UTF-8''编码），并流式传输防OOM。
用 http.ServeFile 快速提供静态文件下载
如果只是让客户端直接下载一个已知路径的文件（比如 /tmp/report.pdf），http.ServeFile 是最轻量的选择。它会自动设置 Content-Disposition: attachment（前提是 URL 路径含扩展名且未被其他中间件覆盖），并处理范围请求（Range）、缓存头等。
但要注意：http.ServeFile 会把文件路径当作 URL 路径的一部分暴露，不建议直接传用户输入的路径，否则可能触发目录遍历漏洞（如 ../../../etc/passwd）。
- 只用于可信、固定路径，例如
http.ServeFile(w, r, "/var/www/downloads/latest.zip") - 若路径来自参数，必须先做白名单校验或使用
filepath.Clean+ 根目录约束 - 它不会自动重命名下载文件；最终文件名由浏览器根据 URL path 最后一段决定
手动设置 Content-Disposition 实现自定义文件名下载
多数业务场景需要隐藏真实路径、统一输出名（如 订单导出-20240520.xlsx），这时得自己控制响应头。关键在于三步：设 Content-Type、设 Content-Disposition、写文件流。
常见错误是忘记调用 w.Header().Set() 或写错 attachment; filename= 的编码格式——中文名必须用 filename*=UTF-8''... 编码，否则 Chrome/Firefox 可能乱码或截断。
立即学习“go语言免费学习笔记（深入）”；
-
Content-Type建议用application/octet-stream（通用二进制），避免 MIME 类型探测干扰 - 英文名：直接用
attachment; filename="report.pdf" - 中文名：用
attachment; filename*=UTF-8''%E8%AE%A2%E5%8D%95%E5%AF%BC%E5%87%BA.xlsx（URL 编码后） - 务必在
io.Copy前完成所有 Header 设置，否则会触发http: multiple response.WriteHeader calls
func downloadHandler(w http.ResponseWriter, r *http.Request) {
filename := "订单导出-20240520.xlsx"
filepath := "/data/export/12345.xlsx"
w.Header().Set("Content-Type", "application/octet-stream")
w.Header().Set("Content-Disposition", `attachment; filename*=UTF-8''`+url.PathEscape(filename))
f, err := os.Open(filepath)
if err != nil {
http.Error(w, "file not found", http.StatusNotFound)
return
}
defer f.Close()
io.Copy(w, f)
}
大文件下载要避免内存爆满：用 io.Copy + bufio.Reader
直接 os.ReadFile 读整个文件到内存再写入响应体，对几百 MB 以上文件极易 OOM。正确做法是流式传输：打开文件 → 创建带缓冲的 reader → io.Copy 到 ResponseWriter。
默认 io.Copy 内部用 32KB 缓冲区，一般够用；若网络延迟高或磁盘 I/O 慢，可显式用 bufio.NewReaderSize(f, 1 提升吞吐（比如 1MB 缓冲）。
- 不要用
bytes.Buffer或strings.Builder中转大文件内容 - 确保文件打开成功后再设 Header，否则出错时 Header 已发送会导致 panic
- 若需限速或记录进度，可在
io.Copy时包装一个带计数的io.Writer
并发下载多文件打包成 ZIP：用 archive/zip 边写边响应
用户点击“下载全部附件”，后端需把多个文件打成 ZIP 并直接返回。不能先生成临时 ZIP 文件再 ServeFile——浪费磁盘且有竞态风险。应使用 zip.NewWriter 直接写入 http.ResponseWriter。
注意：zip.Writer 需要底层 writer 支持 Write，而 http.ResponseWriter 满足；但必须在所有文件写完后调用 zw.Close()，否则 ZIP 结尾结构缺失，解压失败。
- 每个文件调用
zw.CreateHeader时，Header.Name是 ZIP 内路径，建议用filepath.Base清理掉上级路径 - 避免在
Name中出现../，否则解压可能越界写入 - HTTP Header 仍要设
Content-Type: application/zip和Content-Disposition
func zipDownloadHandler(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "application/zip")
w.Header().Set("Content-Disposition", `attachment; filename="attachments.zip"`)
zw := zip.NewWriter(w)
defer zw.Close()
files := []string{"/data/a.pdf", "/data/b.jpg"}
for _, fp := range files {
f, _ := os.Open(fp)
defer f.Close()
fi, _ := f.Stat()
header, _ := zip.FileInfoHeader(fi)
header.Name = filepath.Base(fp) // 关键：防止路径穿越
header.Method = zip.Deflate
wr, _ := zw.CreateHeader(header)
io.Copy(wr, f)
}
zw.Close() // 必须调用，否则 ZIP 不完整
}
实际部署时最容易被忽略的是：没有检查文件是否存在就设 Header，导致 404 时 Header 已发、Body 空，客户端卡住等待数据；还有 ZIP 场景下忘了 zw.Close()，用户下载的 ZIP 打不开却查不出原因。 
