Go HTTP Range 返回错误长度通常是哪类问题

Go HTTP Range 返回“长度不对”时，通常不是 Range 头本身失效，而是三层数据没有对齐：请求里的起止字节是闭区间，服务端的 Content-Range 与 Content-Length 必须描述本次实际发送的那一段，客户端还可能因为 gzip 自动解压而看到另一种长度。先确认你观察的是哪一层，再定位会快很多。

先用一个公式判断是不是区间长度错了

假设请求是 Range: bytes=100-199，这一段包含首尾两个位置，所以应发送 100 个字节，而不是 99 个。服务端通常返回 206 Partial Content、Content-Range: bytes 100-199/总大小 和 Content-Length: 100。把最后一个位置当成开区间，或把整个文件大小写进 Content-Length，都会让下载器报告长度异常。

排查时把三个数同时记下来：请求的 start/end、资源总大小 size、本次响应体实际应发送的 length。只要单段请求满足 length = end - start + 1，并且 Content-Range 的斜杠后仍是完整资源大小，头部的语义就没有混用。

优先让 ServeContent 负责单文件 Range

如果目标只是提供一个可断点读取的文件，不建议自己同时实现区间解析、Seek、响应头和错误状态。标准库的 http.ServeContent 就是为此设计的，它会处理 Range、MIME 类型和条件请求；但它要求传入的 io.ReadSeeker 可以正常 Seek，并通过 Seek 到末尾计算内容大小。

package main

import (
    "net/http"
    "os"
    "time"
)

func fileHandler(w http.ResponseWriter, r *http.Request) {
    // 打开后交给 ServeContent，避免手工拼接 206、Content-Range 和长度。
    f, err := os.Open("assets/video.mp4")
    if err != nil {
        http.Error(w, "文件不可用", http.StatusNotFound)
        return
    }
    defer f.Close() // 请求结束时释放文件描述符。

    // 文件名只用于推断 MIME；Range 的定位和响应长度由标准库处理。
    http.ServeContent(w, r, "video.mp4", time.Time{}, f)
}

这段代码的关键不是“调用了一个更短的函数”，而是把长度的唯一来源收拢到同一个 ReadSeeker。如果底层对象的 Seek(0, io.SeekEnd) 返回了错误大小，或文件在计算大小后又被替换，Range 仍然可能看起来不对；这时要先保证资源读取的一致性，而不是继续改响应头。

自定义实现时最容易错的是资源大小和响应体

如果后端不是普通文件，而是对象存储、数据库或自定义流，就可能需要自己映射 Range。这时要特别检查四个边界：单段长度是否使用闭区间公式；起止位置是否超过当前资源大小；响应体是否只读这一段；是否在写入响应前设置了与实际片段一致的 Content-Length。

import "fmt"

func rangeLength(start, end, size int64) (int64, error) {
    // 这里的 end 是包含在内的最后一个字节位置。
    if start = size {
        return 0, fmt.Errorf("range 越界: %d-%d/%d", start, end, size)
    }
    // 加一是因为 HTTP byte range 使用闭区间。
    return end - start + 1, nil
}

示例只计算长度，不代表完整的 Range 解析器。正式实现还要处理后缀范围、多个范围、没有重叠的范围以及资源在读取期间发生变化的情况。Go 标准库源码中的 parseRange 和 httpRange.contentRange 可以作为语义参考，但不要把源码中的内部类型当成公共 API 使用。

客户端看到的长度不一定是线上传输长度

另一类常见误判发生在客户端：服务器返回了压缩内容，Go 的 Transport 默认可能自动解压。官方文档说明，解压后 Response.Uncompressed 会变为 true，ContentLength 会被设为 -1，同时删除响应中的 Content-Length 和 Content-Encoding 字段。此时不要拿解压后的 io.Copy 字节数去和线上压缩包大小直接比较。

client := &http.Client{
    Transport: &http.Transport{
        // 关闭自动解压，便于对照线上 Content-Length 和原始 Range 响应。
        DisableCompression: true,
    },
}

req, err := http.NewRequest(http.MethodGet, "https://example.com/video.mp4", nil)
if err != nil {
    return err
}
req.Header.Set("Range", "bytes=100-199") // 只请求一个闭区间片段。

resp, err := client.Do(req)
if err != nil {
    return err
}
defer resp.Body.Close() // 无论状态码如何，都要关闭响应体。

这里只是为了诊断原始响应；生产代码是否关闭压缩，要结合带宽、缓存和 Range 语义决定。若确认没有压缩，仍然是长度不一致，就回到服务端检查资源总大小、区间公式和响应体读取边界。

和手工拼响应头相比，采用标准库的取舍

ServeContent 适合稳定的可 Seek 资源，优点是 Range、条件请求和 MIME 处理集中，缺点是你的数据源必须满足它的读取模型。手工实现适合对象存储代理或动态切片，但要承担协议边界、并发修改、缓存和多段响应的全部责任。不要只修一个 Content-Length 就结束排查。

• 优先用 ServeContent：本地文件或可稳定 Seek 的归档资源。
• 考虑自定义映射：对象存储已经给出可靠的区间读取结果，Go 只做代理。
• 先保留原始信息：排障时记录状态码、Range、Content-Range、Content-Length、Content-Encoding 和实际读取字节数。

常见问题

Range=bytes=0-99 为什么 Content-Length 应该是 100？

因为首尾位置都包含在内，长度是 99-0+1。斜杠后的总大小另表示完整资源大小，不是本次发送长度。

ServeContent 仍然返回错误长度怎么办？

先检查传入的 ReadSeeker 是否能正确 Seek 到末尾，以及文件是否在计算大小和读取片段之间被替换；这两类问题比继续覆盖响应头更常见。

为什么 Go 客户端的 ContentLength 是 -1？

可能是自动解压后长度不再对应线上编码数据，也可能是服务端没有提供固定长度。结合 Uncompressed、编码头和实际读取结果判断。

总的判断顺序是：先算闭区间，再核对资源大小，接着确认响应体是否只包含该区间，最后排除客户端自动解压。四层数据一致后，Range 的“错误长度”通常就能定位到具体一层。