http.ServeFile可快速提供静态文件下载，但存在路径遍历风险，需用filepath.Clean校验并限制在允许目录内；不支持断点续传；强制下载需设Content-Disposition为attachment，中文名需URL编码；大文件应io.Copy流式传输并处理连接中断。
用 http.ServeFile 快速提供静态文件下载
直接暴露文件路径给客户端下载，最简方式就是 http.ServeFile。它会自动设置 Content-Disposition: attachment（如果请求带 download 参数或路径含扩展名），但注意：它不校验路径，../ 可能导致任意文件读取。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- 永远用
filepath.Clean()规范路径，再检查是否在允许目录内，例如：allowedDir := "/var/www/downloads" path = filepath.Clean(path) if !strings.HasPrefix(path, allowedDir) { http.Error(w, "Forbidden", http.StatusForbidden) return } - 不要直接传用户输入的
r.URL.Path给http.ServeFile，先提取文件名并白名单校验（如只允许.pdf、.zip） -
http.ServeFile不支持断点续传（Range请求），大文件场景慎用
手动设置 Content-Disposition 控制下载行为
想强制浏览器下载而非预览，必须显式设置响应头。关键不是 Content-Type，而是 Content-Disposition 的 attachment 模式。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 用
w.Header().Set("Content-Disposition", `attachment; filename="report.pdf"`)，注意filename值需用双引号包裹，且不含路径（只留文件名） - 中文文件名要 URL 编码并加
filename*=UTF-8''...，否则 Chrome/Firefox 表现不一致：filename := url.PathEscape("报告_2024.pdf") w.Header().Set("Content-Disposition", fmt.Sprintf(`attachment; filename="%s"; filename*=UTF-8''%s`, filename, filename)) - 设完
Content-Disposition后，再调用http.ServeFile或自己io.Copy，顺序不能反
用 io.Copy + os.Open 实现流式传输与权限控制
需要鉴权、日志、限速或动态生成文件时，得绕过 http.ServeFile，自己读文件写响应体。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 打开文件后立即检查错误，避免后续写 header 时已无法修改状态码：
f, err := os.Open(filepath.Join(baseDir, name)) if err != nil { http.Error(w, "File not found", http.StatusNotFound) return } defer f.Close() - 用
w.Header().Set("Content-Length", ...)提前设大小，有助于客户端显示进度；若不确定大小（如压缩流），就别设，让 Go 自动用 chunked encoding - 大文件务必用
io.Copy，别用io.ReadAll全部读进内存，否则 1GB 文件直接 OOM
处理并发下载与连接中断
Go HTTP server 默认对每个连接启用 keep-alive，但文件下载过程中客户端关浏览器、网络断开，会导致 goroutine 卡住或 io.Copy 返回 net.ErrClosed 类错误。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 在
io.Copy后检查 error 是否为net.ErrClosed或http.ErrHandlerTimeout，这类错误可忽略（不打 ERROR 日志） - 用
context.WithTimeout包裹 handler，防止慢客户端拖垮服务，但 timeout 时间要大于最大文件传输预期耗时 - 如果需精确统计下载完成率，得监听
ResponseWriter是否已写入（通过包装http.ResponseWriter实现Hijack或用http.NewResponseController（Go 1.22+））
