单纯调 r.MaxMultipartMemory 不会延长时间,只放宽内存限制;真正卡住上传的是 Go Server、Gin 和 Nginx 三层超时机制,须同步调整:Go 层设 ReadTimeout(覆盖 header+body 全程),Gin 层设 MaxMultipartMemory(避免“request body too large”误判),Nginx 层也需配置对应超时。

单纯调 r.MaxMultipartMemory 不会延长时间,只放宽内存限制;真正卡住上传的,是三层独立的超时机制在同时起作用——必须同步改 Go Server、Gin 和 Nginx,缺一不可。
Go HTTP Server 层要显式设 ReadTimeout
默认值是 0(不限制),但实际受底层 TCP keepalive 影响,且不生效于大文件流式读取。不设它,连接可能在 body 还没读完时就被静默关闭。
- 启动 server 时必须显式传入:
http.Server{Addr: ":8080", ReadTimeout: 10 * time.Minute} -
ReadTimeout是从连接建立开始计时,覆盖 header 解析 + body 读取全过程 - 别用
WriteTimeout替代——它只管响应阶段,对上传无影响
Gin 引擎层要调 MaxMultipartMemory 避免提前报错
这个值不是超时开关,而是 multipart 解析的内存阈值。设小了会直接返回 http: request body too large,看起来像超时,其实是被拦在解析入口。
- 初始化后立即设置:
r := gin.Default(); r.MaxMultipartMemory = 256 - 设为 0 表示完全禁用内存限制(不推荐),设太大可能引发 OOM
- 注意:该配置不影响超时,只决定 multipart parser 是否触发、以及能否容纳整个文件头+元数据
Nginx 反向代理层必须配齐三个参数
如果请求根本没进 Gin,那改 Gin 和 Go 都白搭。Nginx 在收到第一个字节后就开始倒计时,卡在中间就直接 504 或断连。
-
client_body_timeout 300s:两次数据包之间的最大空闲间隔(不是总上传时间) -
proxy_read_timeout 600s:Nginx 等待 Gin 返回响应的最长时间,必须 ≥ Go 的ReadTimeout -
client_max_body_size 1g:否则直接返回 413,连超时机会都没有 - 别漏掉
proxy_send_timeout,尤其当 Gin 合并分片后再返回结果时,它控制 Nginx 往浏览器发响应的耐心
c.FormFile 调用时机决定你能不能拿到文件
很多人以为超时发生在 c.FormFile 执行中,其实它只是“触发器”——首次调用才开始解析整个 multipart body。在此之前,请求体还躺在 socket 缓冲区里没动。
- 一旦调用
c.FormFile("file"),Gin 就开始读取并解析 body,此时才真正进入超时倒计时 - 名字必须和前端
FormData.append("file", ...)完全一致,错一个字符就返回nil, nil,不会报错 - 后续再调同名
c.FormFile会返回nil, error,因为 body 已被消费过一次 - 若需可靠上传,别依赖单次
c.FormFile,应切换成分片方案,用c.Request.MultipartReader()手动流式读取
最容易被忽略的是 client_body_timeout 的语义——它不是“总上传耗时”,而是“两次数据包之间允许的最大空闲时间”。弱网环境下,哪怕总时间没超,只要中间卡顿超过这个值,Nginx 就会断开连接,且不会重试。

















