Gin 不自动解析 multipart 表单，需手动调用 ParseMultipartForm；否则 c.FormFile 返回 nil 和错误。常见原因包括未调用解析、maxMemory 设置不当或前端 enctype 错误。
Gin 本身不处理文件上传逻辑，它只提供 c.FormFile 和 c.MultipartForm 这两个接口来读取已由 Go 标准库解析好的 multipart 数据 —— 所以“上传失败”八成不是 Gin 的锅，而是你没调用 ParseMultipartForm、没检查 maxMemory 限制，或者前端没发对 enctype="multipart/form-data"。
为什么 c.FormFile 总是返回 nil, err？
这是最常见卡点：Gin 不会自动解析 multipart 表单。你必须在调用 c.FormFile 前，显式触发解析，否则 c.Request.MultipartForm 为空，c.FormFile 就只能报 http: no such file 或直接 panic。
实操建议：
- 在路由 handler 开头加
c.Request.ParseMultipartForm(32 （32MB 内存缓冲），或更稳妥地用 <code>c.MaxMultipartMemory = 32 在初始化 Gin 引擎时全局设置 - 如果只传小文件，不设也行，但 Go 默认只用 32KB 内存解析，超了就写临时文件 —— 此时仍需先调用
ParseMultipartForm，否则拿不到FormFile - 检查前端
<form>是否漏了enctype="multipart/form-data"，这个漏掉会导致后端收到的是普通表单，FormFile必然为空
c.FormFile 和 c.MultipartForm 该怎么选？
二者底层都依赖 http.Request.ParseMultipartForm，但封装层级不同，适用场景明确：
立即学习“go语言免费学习笔记（深入）”；
-
c.FormFile("avatar")：适合单文件上传，返回*multipart.FileHeader，轻量直接，够用就别绕路 -
c.MultipartForm()：返回完整*multipart.Form，含File（map[string][]*multipart.FileHeader）和Value（普通字段），适合多文件 + 文本字段混合提交，比如上传头像 + 填写昵称 + 选择分类 - 注意：
c.MultipartForm()内部会自动调用ParseMultipartForm，而c.FormFile不会 —— 所以混用时顺序很重要：先c.FormFile就得自己 parse；先c.MultipartForm后续再调c.FormFile就没问题
保存文件时容易踩的坑有哪些？
拿到 *multipart.FileHeader 后，用 Open() 和 io.Copy 保存是标准流程，但几个细节决定成败：
-
fileHeader.Filename是客户端传的原始文件名，**不可信** —— 可能含../路径穿越，也可能带空格、中文、特殊符号，务必重命名或 sanitize（例如用uuid.New().String() + filepath.Ext(fileHeader.Filename)） -
fileHeader.Size是客户端声明的大小，可能被篡改，建议用io.CopyN配合限流，或保存后os.Stat校验 - 临时文件路径由 Go 自动管理，但如果你调了
c.Request.ParseMultipartForm且maxMemory设太小，大文件会先写入系统临时目录（如/tmp），再由你读取 —— 这个过程不报错，但磁盘满或权限不对就会静默失败 - 别忘了
defer src.Close()和dst.Close()，漏关会导致句柄泄漏，尤其高并发上传时很快 hit ulimit
文件上传真正的复杂点不在 Gin，而在边界控制：前端传什么、网络怎么传、服务端内存/磁盘/时间怎么配、文件名怎么处理、错误怎么透出给用户。Gin 只递了把刀，切哪、怎么切、切完擦不擦血迹，都得你自己定。
