Gin 文件下载应优先用 c.File()（需绝对路径+白名单校验）或 c.DataFromReader()（适合大文件/动态生成），禁用 c.Redirect() 避免绕过鉴权；中文文件名用 filename="xxx" 而非 filename*，前端须用 blob/arrayBuffer 触发下载。
用 c.File() 直接返回文件，但路径必须绝对且服务可读
Gin 的 c.File() 是最直接的下载方式，它会自动设置 Content-Disposition: attachment 响应头，触发浏览器下载。但它不校验文件是否存在，也不做路径清理——如果传入相对路径或用户可控路径，极易引发目录遍历漏洞。
常见错误现象：http: invalid path escape "%2e%2e/"（Gin 自动拦截了 ../），或静默返回 404/500 却没报错。
- 始终用
filepath.Abs()转成绝对路径，再与预设的白名单根目录比对 - 不要拼接用户输入的文件名，如
c.Param("name")，必须严格白名单校验或哈希映射 - 若文件在静态资源目录外（比如
/data/uploads/），需确保 Gin 进程对该路径有读权限
// 推荐做法：限定根目录 + 白名单校验
const uploadRoot = "/data/uploads"
fileName := c.Param("file")
if !strings.HasSuffix(fileName, ".pdf") || strings.Contains(fileName, "/") {
c.AbortWithStatus(400)
return
}
absPath := filepath.Join(uploadRoot, fileName)
if !strings.HasPrefix(absPath, uploadRoot) {
c.AbortWithStatus(403)
return
}
c.File(absPath)
用 c.DataFromReader() 控制流式传输和自定义响应头
当需要动态生成文件（如导出 Excel）、或文件太大不宜全量加载进内存时，c.DataFromReader() 更合适。它不走文件系统，而是把一个 io.Reader 直接转为 HTTP 响应体，同时允许你手动设置 Content-Type 和 Content-Disposition。
容易踩的坑：忘记设 Content-Disposition，导致浏览器直接渲染文本/JSON；或未指定 Content-Type，让客户端猜错编码，中文文件名乱码。
立即学习“go语言免费学习笔记（深入）”；
- 文件名含中文时，用
url.PathEscape()编码，避免filename*=UTF-8''...兼容问题 - 务必传入真实文件大小（
size参数），否则无法支持断点续传和进度条 - 若底层 reader 不支持
io.Seeker（比如gzip.Reader），size必须准确，否则可能截断
f, _ := os.Open("report.xlsx")
defer f.Close()
stat, _ := f.Stat()
c.DataFromReader(200, stat.Size(), "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
f, map[string]string{
"Content-Disposition": `attachment; filename="report.xlsx"`,
})
为什么不用 c.Redirect() 或前端 fetch() 触发下载？
有人想用 c.Redirect(http.StatusFound, "/static/file.zip") 让 Nginx 处理下载，这看似省事，但绕过了 Gin 中间件（鉴权、日志、限流失效）；而前端用 fetch() + blob 下载，则无法触发原生下载行为（尤其是大文件），还可能因 CORS 或内存溢出失败。
典型错误场景：登录态存在 Gin Session 中，但重定向到静态路径后，Nginx 不转发 Cookie，导致未授权访问；或前端 fetch() 拿到二进制却调用 response.text()，内容直接损坏。
- 除非静态资源完全公开且无需鉴权，否则别用
c.Redirect()做下载跳转 - 前端必须用
response.arrayBuffer()或response.blob()，再创建URL.createObjectURL()触发<a download> - 超过 100MB 的文件，前端处理风险高，应优先服务端直传
文件名中文乱码、Safari 不弹窗、Chrome 提示“已阻止下载”
这些不是 Gin 的 bug，而是 HTTP 标准和浏览器实现差异。Gin 默认用 RFC 5987 格式写 Content-Disposition，但 Safari 对 filename* 支持不稳定，Chrome 则会拦截非用户手势触发的下载（比如异步 API 返回后自动下载）。
关键点：服务端能控制的只有响应头，客户端行为必须配合调整。
- 中文文件名统一用
filename="filename.txt"（ASCII），不依赖filename*，兼容性最好 - 确保下载请求由用户点击等同步事件发起，避免
setTimeout或 Promise.then 后触发window.location - 若必须用
filename*，注意 Chrome 要求Content-Type不能是text/plain或空，否则降级为 inline
真正难处理的是「用户点了下载按钮，接口也返回了正确响应，但浏览器没反应」——八成是前端没正确处理 blob URL 生命周期，或调用了 revokeObjectURL 太早。
