HTTP响应头需设Content-Disposition: attachment并指定filename，Content-Type须明确设置；大文件下载用io.CopyBuffer控制缓冲区并检查错误；路径需经Join、EvalSymlinks及前缀校验防遍历；并发时每次请求独立打开文件并defer关闭。
HTTP响应头设置不正确导致浏览器直接打开而非下载
浏览器是否触发下载，关键取决于 Content-Disposition 响应头。如果缺失或值为 inline，文件（尤其是 .pdf、.jpg、.txt 等常见类型）大概率被内嵌打开；必须显式设为 attachment 并指定 filename：
w.Header().Set("Content-Disposition", `attachment; filename="report.pdf"`)
w.Header().Set("Content-Type", "application/pdf")
w.Header().Set("Content-Transfer-Encoding", "binary")
w.Header().Set("Content-Length", strconv.FormatInt(fileSize, 10))
- 文件名含中文时，
filename*语法更可靠（如filename*=UTF-8''%E6%8A%A5%E5%91%8A.pdf），但需注意旧版 IE 不支持 - 不要依赖
http.DetectContentType推断类型后直接写入——它只读前 512 字节，对小文件可能误判；优先按业务逻辑明确设置Content-Type - 若用
http.ServeFile，它**不会自动加Content-Disposition**，必须自己包装响应
大文件下载卡死或内存暴涨
直接 io.Copy(w, file) 看似简洁，但若未控制缓冲区或未处理连接中断，易引发 goroutine 泄漏或 OOM。核心是避免一次性加载整个文件进内存：
buf := make([]byte, 32*1024) // 32KB 缓冲区足够，过大无益 _, err := io.CopyBuffer(w, file, buf)
- 用
io.CopyBuffer显式传入缓冲区，比默认的io.Copy更可控 - 务必检查
err：客户端中途关闭连接会返回net.ErrClosed或write: broken pipe，此时应立即return，避免继续读取 - 对超大文件（>1GB），考虑加
http.ServeContent支持断点续传（需提供modtime和size，并处理If-Range/Range头）
文件路径遍历漏洞（Path Traversal）
用户传入的文件名若未经净化，拼接后可能访问任意系统路径，比如 ../../etc/passwd。Golang 没有内置“安全路径拼接”函数，必须手动校验：
func safeFilePath(baseDir, filename string) (string, error) {
path := filepath.Join(baseDir, filename)
resolved, err := filepath.EvalSymlinks(path)
if err != nil {
return "", err
}
if !strings.HasPrefix(resolved, filepath.Clean(baseDir)) {
return "", fmt.Errorf("forbidden path access")
}
return resolved, nil
}
- 必须同时做
filepath.Join+filepath.EvalSymlinks+ 前缀校验，三者缺一不可 - 禁止用
strings.Contains(filename, "..")这类简单字符串检查——绕过方式太多（如....//、URL 编码） - 静态资源下载建议统一走白名单机制：
map[string]string{"report.pdf": "/var/data/reports/2024.pdf"}
并发下载时文件句柄耗尽
每个 os.Open 都占用一个文件描述符（FD），高并发下若未及时关闭，会触发 too many open files 错误。关键不是“怎么开”，而是“何时关”：
立即学习“go语言免费学习笔记（深入）”；
- 务必在
defer file.Close()前确认file非nil，否则 panic - 不要把
os.Open放在http.HandlerFunc外部缓存——文件内容可能变化，且 FD 生命周期难管理 - 若需复用文件句柄（如高频下载同一文件），可用
sync.Pool缓存*os.File，但必须确保Put前已调用Seek(0, 0)重置偏移量
最稳妥的做法仍是每次请求独立打开、显式关闭，并通过 ulimit -n 合理设置系统级 FD 上限。
