gin.Context.FormFile 返回 nil 通常因前端未用 multipart/form-data 提交或后端提前读取了请求体；需确保 Content-Type 正确、字段名匹配、路由无误、中间件未消费 body，并校验文件类型、过滤路径遍历、限制大小。
上传文件时 gin.Context.FormFile 返回 nil
这通常是因为前端没按 multipart/form-data 格式提交，或后端没正确读取请求体。Gin 默认会解析 multipart，但前提是 Content-Type 头必须是 multipart/form-data，且表单字段名要和 c.FormFile("file") 中的字符串完全一致。
常见错误现象：c.FormFile("file") 返回 nil, nil（不是报错），c.MultipartForm() 也为空 —— 很可能请求根本没走对路由，或者被中间件提前消费了 body。
- 确认前端用
FormData构造请求，不要手动设Content-Type（浏览器会自动加 boundary） - 避免在调用
FormFile前执行c.PostForm、c.ShouldBind或任何读 body 的操作，否则 body 流已耗尽 - 检查路由是否用了
OPTIONS预检失败（尤其跨域场景），导致实际 POST 没发出去
保存上传的文档文件到本地磁盘
拿到 *multipart.FileHeader 后，需手动打开源文件流并写入目标路径。Gin 不提供自动保存，也不校验文件扩展名或 MIME 类型，这些都得自己做。
示例关键步骤：
file, header, err := c.FormFile("file")
if err != nil {
c.JSON(400, gin.H{"error": "no file received"})
return
}
// 白名单校验（重要！）
allowedTypes := map[string]bool{
"application/pdf": true,
"application/msword": true,
"application/vnd.openxmlformats-officedocument.wordprocessingml.document": true,
"text/plain": true,
}
if !allowedTypes[header.Header.Get("Content-Type")] {
c.JSON(400, gin.H{"error": "unsupported file type"})
return
}
dst := fmt.Sprintf("./uploads/%s", header.Filename)
if err := c.SaveUploadedFile(file, dst); err != nil {
c.JSON(500, gin.H{"error": err.Error()})
return
}
-
c.SaveUploadedFile是 Gin 封装的便捷方法，底层调用file.Open()+io.Copy，安全可用 - 别直接用
header.Filename当磁盘路径，需过滤掉../等路径遍历字符，否则有目录穿越风险 - 生产环境建议生成唯一文件名（如 UUID + 扩展名），避免同名覆盖或冲突
限制上传大小和超时时间
Gin 默认只允许 32MB 文件，超过会返回 400 Bad Request 并提示 http: request body too large。这个限制由 Go HTTP Server 的 MaxMultipartMemory 控制，不是 Gin 自己的配置。
- 在启动服务前设置：
gin.SetMode(gin.ReleaseMode)后，调用router.MaxMultipartMemory = 8 - 同时需配置 HTTP Server 的
ReadTimeout和WriteTimeout，大文件上传容易触发默认 30 秒超时 - 若用 Nginx 反向代理，还要同步调整
client_max_body_size和proxy_read_timeout，否则请求会在网关层被截断
返回 JSON 响应时文件信息不完整
上传成功后常需返回文件名、大小、URL 等，但 header.Size 是字节数，header.Filename 是客户端传的原始名（不可信），header.Header.Get("Content-Type") 也可能被伪造。
- 真实 MIME 类型应通过
file.Open()读取前几百字节，用net/http.DetectContentType或github.com/gabriel-vasile/mimetype库检测 - URL 字段如果返回 CDN 或静态服务地址，确保路径可公开访问，且权限控制已到位
- 别把
os.Stat结果直接塞进响应（比如 ModTime），Go 的 time.Time JSON 序列化格式易引发前端解析问题，建议转成 ISO8601 字符串
边界情况比想象中多：比如用户上传 .exe 却声称是 .txt，或者空文件、超长文件名、UTF-8 编码异常的文件名——这些不会让 Gin 崩溃，但会让后续处理链出问题。
