Golang实现HTTP断点续传分片下载教程

本文深入剖析了Go语言中实现HTTP断点续传与分片下载的关键技术细节，直击开发者在服务端响应Range请求时极易踩坑的核心问题：从正确解析和校验非法Range头、安全计算字节范围，到严格设置Content-Range、Accept-Ranges等响应头及206状态码，再到避免OOM的文件随机访问与精准字节传输（使用file.Seek+io.CopyN而非全量读取），并覆盖bytes=0-等兼容性陷阱、并发安全、超时控制等生产级考量——不仅告诉你“怎么做”，更清晰揭示“为什么必须这样写”，助你写出健壮、标准、可落地的断点续传服务。

Go HTTP 服务端怎么正确响应 Range 请求

Go 标准库的 http.ServeFile 和 http.FileServer 默认不支持断点续传，直接返回 200，客户端一断就重头下。必须自己解析 Range 头、计算偏移、返回 206 和对应字节块。

关键不是“能不能”，而是“怎么避免踩坑”：

• Range 头可能缺失、格式错误（如 bytes=abc-）、范围越界（bytes=1000-2000 但文件只有 500 字节），不能直接 strings.Split 后强转
• 必须设置 Content-Range 响应头，格式为 bytes 100-199/1000，少斜杠、错顺序、用错单位都会让客户端拒绝接收
• 返回状态码必须是 206 Partial Content，不是 200 OK；否则浏览器或 wget 会丢弃已有缓存，重开连接
• 文件需以只读+随机访问方式打开（os.OpenFile(path, os.O_RDONLY, 0)），不能用 os.ReadFile 全读进内存——大文件直接 OOM

如何安全解析 Range 并校验边界

别手写正则或切片解析。用标准库 http.ParseRange，它已处理各种非法格式并返回明确错误：

ranges, err := http.ParseRange(r.Header.Get("Range"), fileInfo.Size())
if err != nil {
    // err 可能是 "invalid range" 或 "range not satisfiable"
    http.Error(w, "Range Not Satisfiable", http.StatusRequestedRangeNotSatisfiable)
    return
}
if len(ranges) == 0 {
    // 没有合法 Range，按普通请求处理（可选）
    http.ServeFile(w, r, path)
    return
}
// 只取第一个 Range，HTTP/1.1 不允许多段
ra := ranges[0]

注意：http.ParseRange 的第二个参数是文件总大小，必须提前通过 os.Stat 获取；如果传 0 或负数，它会直接返回错误。

常见错误：用 io.Copy 直接从文件开头复制到 ra.End —— 这会读满整个区间，但没跳过前面字节。必须先 file.Seek(ra.Start, 0)。

客户端发 Range: bytes=0- 却收不到完整文件？

这是最典型的兼容性陷阱：bytes=0- 表示“从 0 到末尾”，但 http.ParseRange 解析后，ra.End 是 -1（表示无限），而你的代码若写成 io.CopyN(w, file, ra.End-ra.Start) 就会 panic。

正确做法是显式处理 ra.End == -1：

if ra.End == -1 {
    ra.End = fileInfo.Size() - 1 // 注意：End 是闭区间，所以减 1
}
length := ra.End - ra.Start + 1
w.Header().Set("Content-Range", fmt.Sprintf("bytes %d-%d/%d", ra.Start, ra.End, fileInfo.Size()))
w.Header().Set("Accept-Ranges", "bytes")
w.Header().Set("Content-Length", strconv.FormatInt(length, 10))
w.WriteHeader(http.StatusPartialContent)
file.Seek(ra.Start, 0)
io.CopyN(w, file, length)

漏掉 Accept-Ranges: bytes 头，某些旧版 Android WebView 或 wget 会认为服务器不支持断点，自动降级为全量下载。

为什么用 io.CopyN 而不是 io.Copy？

io.Copy 会一直读到源 EOF，但你只该发指定长度的字节。如果文件被并发修改变长，或者底层存储异常多返回数据，io.Copy 可能多写、破坏响应体完整性，导致客户端校验失败或解包出错。

更稳的做法是封装一个带长度限制的 reader：

type limitedReader struct {
    r io.Reader
    n int64
}
func (l *limitedReader) Read(p []byte) (int, error) {
    if l.n  l.n {
        p = p[:l.n]
    }
    n, err := l.r.Read(p)
    l.n -= int64(n)
    return n, err
}
// 然后：io.Copy(w, &limitedReader{r: file, n: length})

不过 io.CopyN 已内置该逻辑，够用。唯一要注意：它在读不满时会返回 io.UnexpectedEOF，这不是错误，而是正常结束信号，无需记录日志或告警。

大文件场景下，别忘了设 http.Server.ReadTimeout 和 WriteTimeout，否则慢速客户端拖住连接，耗尽 goroutine。

今天带大家了解了的相关知识，希望对你有所帮助；关于Golang的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~