iris 框架无一键下载函数，需手动设 content-disposition 头并用 servefile() 或 servecontent() 输出文件；servefile() 适用于静态文件，须设头防 inline、校验路径；servecontent() 适用于动态/受控场景，需提供 io.readseeker 等参数；中文文件名需 filename* 和 filename 双设并转义，防范路径遍历；二者均不支持 range，大文件需手动处理。
Iris 框架本身不提供「一键下载」封装函数，但实现文件下载非常直接——核心就是设置正确的 Content-Disposition 响应头，并用 ctx.ServeContent() 或 ctx.ServeFile() 流式输出文件。关键不在“怎么调”，而在“怎么设头+怎么传数据+怎么防踩坑”。
用 ctx.ServeFile() 实现静态文件下载
适用于已知路径、无需权限校验的简单场景（如公开的 PDF、ZIP）。它会自动设置 Content-Type 和 Content-Length，但默认是 inline 显示，必须手动覆盖 Content-Disposition 才能触发下载弹窗：
-
ctx.Header("Content-Disposition", "attachment; filename=\"report.pdf\"")—— 注意 filename 必须是 ASCII，中文需用url.PathEscape()编码 - 路径必须是服务端绝对路径或相对于可执行文件的相对路径；若用相对路径，确保运行时工作目录正确（推荐用
os.Executable()+filepath.Dir()构造） - 不要在
ServeFile()前写任何响应体（如ctx.WriteString()），否则会 panic：「http: superfluous response.WriteHeader call」
用 ctx.ServeContent() 实现动态/受控文件下载
当你需要鉴权、限速、生成临时文件、或从数据库/对象存储读取字节流时，ServeContent() 是更安全的选择。它要求你提供 io.ReadSeeker、修改时间、ETag 和内容长度：
-
file, _ := os.Open("./data/export.csv")→ 传给ServeContent()前必须确认file.Stat().Size()和file.Stat().ModTime() - 如果文件内容是内存中生成的（如 CSV 字符串），用
bytes.NewReader([]byte(data))包装，但注意它不支持Seek()—— 此时必须改用ctx.Write()+ 手动设全部 header - 务必调用
defer file.Close()，否则句柄泄漏，Linux 下很快 hit ulimit
常见错误：中文文件名乱码或下载失败
浏览器对 Content-Disposition 中的非 ASCII filename 兼容性极差。Chrome 支持 filename*=UTF-8''xxx，Safari 和旧版 Edge 只认 filename 的 ASCII 子集。最稳方案是 fallback：
- 优先设置：
ctx.Header("Content-Disposition", fmt.Sprintf(`attachment; filename="%s"; filename*=UTF-8''%s`, url.PathEscape(baseName), url.PathEscape(baseName))) - baseName 来自用户输入时，必须过滤掉路径遍历字符（如
../），否则ServeFile()可能读到任意系统文件 - 若仍乱码，退回到纯英文文件名（如
download_20260920.zip），比强撑中文更可靠
真正容易被忽略的是：Iris 的 ServeFile() 和 ServeContent() 都不会自动处理 Range 请求（断点续传）。如果要支持大文件分片下载，得自己解析 ctx.Request().Header.Get("Range") 并用 io.CopyN() 分段写入，这时候就别图省事了——直接上 ctx.ResponseWriter().WriteHeader() + ctx.ResponseWriter().Write() 更可控。
