c.FormFile() 总是返回 nil 或报错的根本原因只有两个:前端字段名不一致,或请求未使用 multipart/form-data 编码;需确保 name 属性与参数完全一致、表单声明 enctype="multipart/form-data"、curl 使用 -F 而非 -d,并检查 err 且合理设置 MaxMultipartMemory。

c.FormFile() 是 Gin 解析上传文件的唯一入口,它不处理普通表单字段,也不解析 JSON 或 query string。用错地方或参数不匹配,直接返回 err != nil,后续调用 file.Filename 会 panic。
为什么 c.FormFile("file") 总是返回 nil 或报错
根本原因只有两个:前端字段名不一致,或请求没走 multipart/form-data 编码路径。
- HTML 表单中
的name必须和c.FormFile("file")的字符串参数**完全一致**(大小写敏感) - 表单必须声明
enctype="multipart/form-data";写成enctype="form/multipart"或漏掉该属性,Gin 根本不会尝试解析文件 - 用
curl测试时,必须用-F "file=@path/to/file";用-d或--data会发成application/x-www-form-urlencoded,c.FormFile()拿不到任何东西 - 没检查
err就直接解引用file,比如file.Filename,会导致 panic
r.MaxMultipartMemory 设置过小导致上传失败
这个值控制 Gin 解析 multipart 请求时允许使用的内存上限,默认是 32 MiB。它不是“文件大小限制”,而是“解析阶段可用内存上限”。一旦超限,请求在进入路由 handler 前就被拒绝,c.FormFile() 根本不会执行。
- 现象:小图能传,大视频上传失败,日志里只看到
http: request body too large,且c.FormFile()的err是nil—— 实际是解析失败,连FormFile这步都没走到 - 设为
0表示不限制,但极易被恶意请求耗尽内存,不推荐 - 应按业务最大预期设值,比如支持 50MB 视频,则写
r.MaxMultipartMemory = 50 - 该设置必须在
gin.Default()之后、任何r.POST()之前调用,否则无效
保存路径 "./uploads/" + file.Filename 容易出错的三个点
c.SaveUploadedFile() 不会自动创建父目录,也不过滤危险路径,直接拼接极可能引发线上故障或安全漏洞。
- 如果
./uploads/目录不存在,会返回open ./uploads/xxx.png: no such file or directory错误;开发时手动建过,部署时忘了同步,就炸了 - 二进制运行位置不固定(如 systemd 启动时工作目录是
/),./uploads/可能指向根目录下,甚至写到系统关键路径 -
file.Filename可被客户端任意构造,比如传../../etc/passwd,拼接后变成./uploads/../../etc/passwd,造成路径遍历——这是严重安全风险
真正安全的做法是:先用 filepath.Base(file.Filename) 提取干净文件名,再用 os.MkdirAll() 显式创建目标目录,最后拼接绝对路径。任何依赖相对路径或信任原始 Filename 的写法,在生产环境都不可靠。











