使用 ctx.FormFile() 处理单文件上传时，必须设置 form 的 enctype="multipart/form-data"，后端显式调用 ctx.FormFile("file") 获取 *multipart.FileHeader，再通过 file.Open() 读取内容；字段名需前后端一致，否则报 "http: no such file"；默认无大小限制，生产环境需设 router.MaxMultipartMemory。
如何用 ctx.FormFile() 处理单文件上传
单文件上传最常用也最容易出错，核心是别漏掉 multipart/form-data 的表单编码类型，且后端必须显式调用 ctx.FormFile() 获取文件句柄。Gin 不会自动解析文件字段，只靠 ctx.PostForm() 拿不到文件内容。
- 前端
<form enctype="multipart/form-data">必须设置，否则ctx.FormFile("file")返回nil和"no such file"错误 -
ctx.FormFile("file")返回*multipart.FileHeader，不是文件内容本身；要读取内容得再调用file.Open()或file.Seek(0, 0)后用io.Copy() - 若字段名写错（比如前端传
upload，后端写ctx.FormFile("file")），错误信息是http: no such file，不是空指针 panic - 文件大小限制默认无上限，但生产环境务必加
gin.SetMode(gin.ReleaseMode)并配合router.MaxMultipartMemory = 8 （8MB）防内存溢出
多文件上传必须用 ctx.MultipartForm() 而非多次 FormFile()
很多人以为循环调 ctx.FormFile("files") 就能拿多个，实际它每次只返回第一个匹配项——Gin 的 FormFile() 是单次提取，不支持同名多值。真正正确的方式是先用 ctx.MultipartForm() 拿到整个表单结构，再从 form.File["files"] 切片里遍历。
-
ctx.MultipartForm()返回*multipart.Form，其中form.File是map[string][]*multipart.FileHeader，键是 input name，值是该 name 对应的所有文件头 - 前端需用
<input type="file" name="files" multiple>，注意 name 后不能带[]（如files[]），Gin 不识别 PHP 风格数组语法 - 如果只传一个文件但用了
multiple，form.File["files"]长度仍是 1，逻辑可统一处理 - 每个
*multipart.FileHeader都要单独Open()，别复用同一个句柄；关闭顺序建议 defer，避免泄漏
文件保存路径和命名的常见陷阱
本地保存时，os.Create() 的路径拼接、权限控制、扩展名校验这三块最容易引发线上问题，尤其是 Windows 和 Linux 路径分隔符不一致、用户上传 .php 文件被直接写入 webroot 等。
- 别用
filepath.Join(uploadDir, header.Filename)直接拼接——攻击者可传../../etc/passwd触发路径穿越；必须用filepath.Base(header.Filename)截取纯文件名 - 扩展名不要信任客户端
header.Header.Get("Content-Type")，它可伪造；应读取文件前几个字节用mimes.TypeByExtension()或第三方库校验 - 生成唯一文件名推荐用
uuid.New().String() + filepath.Ext(filename)，避免并发重名；os.O_CREATE | os.O_WRONLY | os.O_TRUNC是安全写入标配 - 保存目录需提前
os.MkdirAll(uploadDir, 0755)，否则首次上传会报no such file or directory
上传接口返回 JSON 时别忽略 ctx.Abort() 和状态码
上传失败时如果只写 ctx.JSON(400, ...) 不调 ctx.Abort()，后续中间件或 handler 仍会执行，可能造成重复保存、空指针 panic 或错误响应体叠加。
- 所有提前退出分支（如文件为空、大小超限、扩展名禁止）都必须紧跟
ctx.Abort()，确保流程终止 - 成功响应建议用
ctx.JSON(201, map[string]interface{}{"url": "/uploads/xxx.jpg"})，不用 200 —— 201 更符合上传资源创建语义 - 错误响应体统一用
map[string]string{"error": "xxx"}，避免混用 struct 或自定义 error 类型导致前端解析失败 - 别在上传 handler 里直接
log.Printf记录文件名，敏感信息可能泄露；应记录header.Size和filepath.Ext(filename)即可
文件上传看着简单，但路径处理、多文件边界、中断恢复、大文件流式写入这些点，一旦漏掉一个就容易在线上卡住半天。尤其注意 FormFile() 和 MultipartForm() 的语义差异，这是最多人反复踩坑的地方。
