c.FormFile()上传大文件失败根本原因是其依赖ParseMultipartForm,而该方法受r.MaxMultipartMemory默认32MiB限制,超限时Gin在解析阶段即返回400错误,c.FormFile()根本未执行;正确方案是用c.Request.MultipartReader()流式处理分片。

为什么c.FormFile()一上传大文件就400或OOM
根本不是 Gin “不支持”大文件,而是 c.FormFile() 依赖 ParseMultipartForm,而该方法受 r.MaxMultipartMemory 严格限制——默认仅 32 MiB。请求体(含所有字段+文件)超限,Gin 在解析阶段直接返回 http: request body too large,c.FormFile() 根本没机会执行,err 为 nil,但后续逻辑全失效。
常见表现:小文件 OK,100MB 视频上传直接 400;日志里看不到 no such file,只有笼统的 size 错误;你检查了 err 却没发现它根本没走到 FormFile 这步。
-
r.MaxMultipartMemory必须在gin.Default()之后、任何路由注册之前设置,设为0表示不限制内存——但这属于危险操作,可能被恶意请求拖垮服务 - 即使调高
MaxMultipartMemory,单次读取整个 multipart body 仍会吃光内存或触发超时,这不是可扩展方案 - 真正可行的路径是绕过
FormFile,改用c.Request.MultipartReader()或原始io.ReadCloser流式处理
怎么用 MultipartReader 流式接收而不爆内存
分片上传不靠 Gin 自动解析,而靠你手动拉取 multipart boundary 流。关键在于:不把整个请求体加载进内存,而是边读边写入临时文件或缓冲区。
核心步骤是调用 c.Request.MultipartReader() 得到 multipart.Reader,再循环 NextPart() 区分元数据字段(如 identifier、chunkNumber)和文件流部分。对文件 part,直接 io.Copy(dst, part),不经过 SaveUploadedFile。
- 必须提前创建临时目录,例如
os.MkdirAll(fmt.Sprintf("/tmp/uploads/%s", identifier), 0755),否则os.Create报no such file or directory - 不要用
c.FormValue("chunkNumber")——分片请求中该字段可能不在表单头里,或大小写不一致;务必从part.FormName()中提取 - 每个分片文件建议加
.part后缀,合并前不重命名,避免并发时误读未写完的文件 - 若前端用
Content-Range头(如bytes 5242880-10485759/104857600),需用c.GetHeader("Content-Range")解析偏移,并用os.OpenFile(, os.O_WRONLY|os.O_CREATE)+file.Seek()写入对应位置
分片上传必须配套的三项状态管理
断点续传不是“多传几次”,而是靠服务端持久化记录每个文件的上传进度。没有这三项,分片上传就是裸奔。
- 唯一标识:必须用文件内容哈希(如
md5或sha256)生成fileId,不能依赖文件名——否则同名不同内容会覆盖 - 分片索引映射:存一个
map[fileId][]int或数据库表,记录哪些chunkNumber已成功写入磁盘 - 临时文件生命周期:每个分片落地后,必须立即 fsync;合并完成后,要主动清理
.part文件,否则磁盘悄悄被占满
别省略 os.File.Sync() —— 云服务器或容器环境下,write 缓存可能延迟落盘,导致合并时读到空/截断内容。
前端传参和后端校验最容易漏掉的三处
很多线上问题不是逻辑错,而是字段名、头信息、边界值没对齐。
- 前端
必须显式声明enctype="multipart/form-data";用axios.post(url, form, { headers: {} })时,若手动设了Content-Type,会覆盖浏览器自动生成的boundary,导致后端解析失败 -
c.FormFile("video")的字符串必须和完全一致——大小写、下划线、中划线都敏感;file == nil && err == nil代表该字段无内容,不是错误 - 保存前不校验
header.Size和Content-Type就等于开门迎客:file.Size > 5*1024*1024要拒绝;file.Header.Get("Content-Type")只允许"video/mp4"等白名单类型;目标路径必须用path.Base(file.Filename)截取,再拼 UUID 前缀
最易忽略的是:Nginx 或其他反向代理默认有 client_max_body_size 1m,哪怕 Gin 层面全放开,请求也卡在网关层直接 413。必须同步调大代理配置。











