Go 实现 HTTP Range 下载：用 ServeContent 支持断点续传和视频拖动

做文件下载、音视频预览和大对象分片读取时，经常会碰到一个看似前端需求、实际需要后端配合处理的问题：浏览器带着 Range: bytes=... 请求某一段内容，Go 服务不能只返回整份文件。更稳妥的做法是让响应支持 HTTP Range 规则：合法范围返回 206 Partial Content，越界范围返回 416 Range Not Satisfiable，普通请求仍然可以返回 200 OK 的完整内容。Go 标准库里的 http.ServeContent 已经处理了大部分细节，生产代码通常不需要自己手写完整的 Range 解析器。

Range 解决的是“只取一段内容”的需求

浏览器播放较大的 MP4 文件时，用户把进度条拖到中间位置，浏览器不会从文件开头重新下载全部内容。它会带上 Range 请求头，告诉服务端自己想要的字节区间。

Range: bytes=1048576-2097151

如果服务端支持范围响应，返回状态码通常是 206 Partial Content，并用 Content-Range 说明这段数据在完整文件里的起始和结束位置。

HTTP/1.1 206 Partial Content
Accept-Ranges: bytes
Content-Range: bytes 1048576-2097151/8388608
Content-Length: 1048576

如果请求范围超出了文件总长度，服务端应该返回 416 Range Not Satisfiable。如果客户端没有发送 Range，那就按普通下载逻辑返回整份文件。把这些边界理清楚之后，前端下载、视频拖动和失败重试的表现都会顺畅很多。

Go 里优先用 ServeContent，不要急着手写解析

http.ServeContent 是标准库里专门处理内容响应的工具函数。只要传进去的对象实现了 io.ReadSeeker 接口，它就能根据请求头自动处理 Range、缓存相关头和内容类型探测。常见的本地文件句柄 *os.File 就满足这个接口要求。

package main

import (
    "log"
    "net/http"
    "os"
    "path/filepath"
)

func downloadHandler(w http.ResponseWriter, r *http.Request) {
    name := filepath.Base(r.URL.Query().Get("file"))
    if name == "" {
        http.Error(w, "missing file", http.StatusBadRequest)
        return
    }

    path := filepath.Join("./files", name)
    f, err := os.Open(path)
    if err != nil {
        http.NotFound(w, r)
        return
    }
    defer f.Close()

    stat, err := f.Stat()
    if err != nil || stat.IsDir() {
        http.Error(w, "invalid file", http.StatusNotFound)
        return
    }

    w.Header().Set("Content-Disposition", `inline; filename="`+stat.Name()+`"`)
    http.ServeContent(w, r, stat.Name(), stat.ModTime(), f)
}

func main() {
    http.HandleFunc("/download", downloadHandler)
    log.Fatal(http.ListenAndServe(":8080", nil))
}

这段示例代码写得很精简，但有几个点不能省：文件名用 filepath.Base 做一层收敛，避免用户直接传入路径导致的穿越漏洞；打开文件后要记得主动关闭；传给 ServeContent 的修改时间尽量使用真实稳定的值，浏览器和代理服务会用它做缓存判断。

用 curl 验证 206、200 和 416 响应

写完接口后，不要只在浏览器里点一下确认能下载就完事。用 curl 直接发送 Range 请求，能更清晰地看到返回头是否符合预期。

curl -i -H "Range: bytes=0-99" \
  "http://localhost:8080/download?file=demo.mp4"

正常情况下，你应该看到 206 Partial Content，并且 Content-Length 接近 100。再测一次不带 Range 的普通请求：

curl -I "http://localhost:8080/download?file=demo.mp4"

这个请求应该返回 200 OK。最后测一个明显越界的范围：

curl -i -H "Range: bytes=999999999999-" \
  "http://localhost:8080/download?file=demo.mp4"

越界时通常会得到 416，并带上形如 Content-Range: bytes */文件长度 的提示。这个检查很重要：如果越界仍然返回 200，前端可能以为服务端支持分段，实际却拿到完整文件，视频拖动和断点续传的表现都会变得很奇怪。

哪些场景不适合直接套用

ServeContent 虽然省心，但它不是万能的文件网关。它需要可 Seek 的内容，如果数据来自即时压缩流、远程对象流、数据库大字段流式读取，就不能直接把普通 io.Reader 塞进去期待 Range 自动生效。

如果文件来自对象存储，很多团队会把 Range 请求原样转发给对象存储，让它直接返回片段内容，再由业务服务透传必要的响应头。这样能减少业务进程的带宽压力，也避免自己维护复杂的分片读取逻辑。

上线前别漏掉代理、权限和资源检查

Range 接口在本地跑通之后，线上环境还要多校验几层。Nginx、CDN、对象存储网关都可能修改响应头和影响缓存行为；鉴权逻辑如果只保护下载入口，却把真实文件地址暴露出去，也会被绕开权限校验。

• 代理层：确认 Accept-Ranges、Content-Range、Content-Length 没有被错误修改。
• 权限层：Range 只是传输能力，不应该绕过登录态、订单状态、文件归属的校验。
• 资源层：每个 Range 请求都可能打开文件句柄，高并发下载场景要关注句柄数上限和磁盘吞吐能力。
• 类型层：视频预览场景要给出正确的 Content-Type，否则浏览器可能直接触发下载而不是在线播放。
• 兜底层：不支持 Range 的客户端仍然应该能拿到完整内容，除非业务有明确的禁止规则。

相关问题

Go 的 http.ServeFile 能不能支持 Range？

可以。http.ServeFile 内部也会走类似的内容服务逻辑，适合简单静态文件响应场景；如果你已经自己打开了文件、需要自定义文件名或修改时间，ServeContent 使用起来更灵活。

Range 请求一定要返回 Accept-Ranges 吗？

Accept-Ranges: bytes 能明确告诉客户端服务端支持字节范围请求。实际效果还要看服务端是否能正确响应 Range 请求并返回 206。

为什么视频拖动时会发很多 Range 请求？

浏览器需要快速拿到新进度点附近的数据，还可能预读后续的视频片段。服务端要把这类请求当成正常业务行为处理，不要把每个片段请求都误判成异常下载。

手写 Range 解析有没有必要？

只有在非常定制的存储层、权限模型或多源合并下载场景里才值得手写。普通本地文件和内存内容的场景，优先用标准库能避开很多协议细节的坑。

Go 开发支持断点续传和视频拖动的文件响应能力，关键不是把文件读出来写给浏览器，而是正确处理 HTTP Range 这套边界逻辑。优先使用 http.ServeContent，再把鉴权、文件定位、代理响应头和资源限制这些点补齐，代码会比手写一整套分段逻辑更容易维护。