当前位置：首页 > 文章列表 > Golang > Go教程 > Go 实现 HTTP Range 下载：用 ServeContent 支持断点续传和视频拖动

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

来源：17golang原创 2026-07-09 02:02:28 0浏览收藏

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

要点速览

Range 请求让浏览器只取文件的一段，常见于断点续传、视频拖动和大文件预览场景。
Go 里优先使用 http.ServeContent，前提是传入的内容支持 Seek 并提供稳定的修改时间。
支持片段响应时要关注 206、Content-Range、Accept-Ranges 和 416 的行为。
上线前要检查代理缓冲、鉴权校验、文件句柄关闭、Content-Type 配置和大文件并发读取的资源占用。

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 HTTP Range 请求路径：浏览器发送 Range 头，Go Handler 返回 206 片段或 416 越界 — 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，前端可能以为服务端支持分段，实际却拿到完整文件，视频拖动和断点续传的表现都会变得很奇怪。

Go http.ServeContent 处理 ReadSeeker 文件，返回 206 片段并保留 200 兜底路径 — `ServeContent` 负责处理范围响应的协议细节，业务代码更应该把精力放在文件定位、权限校验和资源释放上。

哪些场景不适合直接套用

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

数据来源	是否适合 ServeContent	处理建议
本地文件	适合	`*os.File` 支持 Seek，优先使用标准库实现。
内存字节切片	适合	可以用 `bytes.NewReader` 包装成 ReadSeeker 接口。
实时压缩输出	不适合	内容长度和偏移不稳定，通常走普通流式下载逻辑。
对象存储私有文件	看情况	可转发 Range 请求到对象存储，或用预签名地址让存储服务自行处理。