c.File()不支持断点续传,因其底层调用http.ServeFile,不解析Range头、不返回206状态码,且将整个文件读入内存,易导致OOM;应改用c.DataFromReader()手动实现Range逻辑,并配置Nginx绕过缓存。

为什么c.File()不支持断点续传
c.File()底层调用http.ServeFile,它不解析Range请求头,也不返回206 Partial Content状态码。客户端发Range: bytes=1024-过来,服务端仍返回200 OK和完整文件——浏览器收不到Content-Range头,进度条卡死,暂停后重连就从头开始。
更隐蔽的问题是:c.File()会把整个文件读进内存再写入响应体。100MB 文件 × 10 并发 = 1GB 内存占用,容易触发runtime: out of memory或被 Nginx/ALB 主动断连。
- 只对 ≤ 1MB 的小文件(如图标、配置)用
c.File() - 路径必须是绝对路径或相对于可执行文件的正确相对路径,否则报
open xxx: no such file or directory - 它自动设
Content-Type和Content-Disposition,但无法控制Accept-Ranges头
用c.DataFromReader()手动支持Range
真正可控的做法是:自己解析Range头,计算起止偏移,用io.CopyN精确读取,再通过c.DataFromReader()下发。关键不是“替换c.File”,而是补全http.ServeContent该干却没干的事。
示例核心逻辑:
f, err := os.Open(filepath.Clean(absPath))
if err != nil {
c.AbortWithStatus(404)
return
}
defer f.Close()
<p>stat, _ := f.Stat()
size := stat.Size()
modTime := stat.ModTime()</p><p>// 必须显式设置,否则客户端不发Range
c.Header("Accept-Ranges", "bytes")
c.Header("Content-Length", strconv.FormatInt(size, 10))
c.Header("Last-Modified", modTime.UTC().Format(http.TimeFormat))</p><p>rangeHeader := c.Request.Header.Get("Range")
if rangeHeader != "" {
ranges, err := http.ParseRange(rangeHeader)
if err != nil || len(ranges) != 1 {
c.AbortWithStatus(416)
return
}
r := ranges[0]
if r.Start > size-1 {
c.AbortWithStatus(416)
return
}
end := r.End
if end == -1 || end >= size {
end = size - 1
}
length := end - r.Start + 1</p><pre class="brush:php;toolbar:false;">f.Seek(r.Start, io.SeekStart)
c.Status(206)
c.Header("Content-Range", fmt.Sprintf("bytes %d-%d/%d", r.Start, end, size))
c.Header("Content-Length", strconv.FormatInt(length, 10))
c.DataFromReader(206, length, "application/octet-stream", io.LimitReader(f, length), nil)
return}
// 无Range头时走完整响应 c.DataFromReader(200, size, "application/octet-stream", f, nil)
-
io.LimitReader(f, length)比io.CopyN更稳妥——它天然处理io.ErrUnexpectedEOF,不会因文件尾提前结束而panic - 必须在
c.DataFromReader()前设好所有header,包括Content-Length和Content-Range(206时) - 中文文件名要加
url.PathEscape(filename)到Content-Disposition,别用QueryEscape
Nginx反向代理下断点续传失效怎么办
如果Gin前面挂了Nginx,Range请求很可能被缓存机制破坏:Nginx默认可能把200响应缓存下来,后续Range请求被错误返回完整文件,或直接416。
必须在Nginx配置里明确绕过缓存:
location /downloads/ {
proxy_pass https://gin-backend;
proxy_cache_bypass $http_range;
proxy_no_cache $http_range;
proxy_ignore_headers Cache-Control Expires Set-Cookie;
# 禁用 gzip 对 Range 请求的影响
gzip_disable "range";
}
-
proxy_cache_bypass $http_range:只要带Range头,就不查缓存,直通后端 -
proxy_no_cache $http_range:强制不缓存任何含Range头的响应(哪怕后端返回Cache-Control: public) - 删掉
proxy_cache_valid 200 206 ...这类配置——206绝不能缓存 - 静态文件直出场景(Nginx直接
root)不用配这些,ngx_http_range_module原生支持
大文件下载中容易被忽略的细节
断点续传能跑通不等于生产可用。几个真实线上踩过的坑:
-
os.Stat().ModTime()若文件被热更新过,会导致412 Precondition Failed;建议用文件元数据固定字段(如创建时间)或干脆去掉If-Modified-Since校验 - 文件句柄泄漏:
defer f.Close()必须有,否则too many open files很快爆满 - 并发下载时,多个goroutine同时
Seek同一个*os.File没问题,但别用bufio.Reader包装它——Seek会破坏buffer内部offset - 客户端若用
fetch或XMLHttpRequest,需显式设responseType = 'blob',否则二进制数据被转成UTF-8字符串导致损坏


















