fastapi 如何实现大文件下载的 Range 支持（断点续传）_网络技术

FileResponse默认不支持Range请求，需手动实现StreamingResponse+Range解析：校验头格式、计算偏移、设置206/416状态码及Content-Range等响应头，并显式声明request: Request参数。

FastAPI 中 `FileResponse` 默认不支持 Range 请求

直接用 FileResponse 返回大文件时，HTTP 响应头里没有 Accept-Ranges: bytes

，客户端发起带 Range: bytes=100-199 的请求会直接返回 200 而非 206，断点续传失效。根本原因是 FileResponse 内部使用的是静态文件流式读取，但没做字节范围解析和部分响应封装。

手动实现 `StreamingResponse` + `Range` 解析

需要自己解析 Range 请求头、计算偏移、设置正确状态码与响应头。核心逻辑包括：校验格式、提取起始/结束位置、读取对应字节块、返回 206 Partial Content 或 200 OK（无 Range 时）。

Range 头格式必须为 bytes=start-end，可能有多个区间（但浏览器下载只发单个），只处理第一个
文件需以二进制模式打开，且支持 seek()（如本地磁盘文件可以，S3 等对象存储需额外适配）
响应头必须包含：Content-Range（如 bytes 100-199/10000）、Accept-Ranges: bytes、Content-Length（当前片段大小）、Content-Type
状态码：有合法 Range 时返回 206；Range 超出文件大小或格式错误，返回 416 Range Not Satisfiable 或回退到 200

示例片段：

@app.get("/download/{filename}") async def download_file(filename: str): file_path = Path("uploads") / filename if not file_path.is_file(): raise HTTPException(404)

stat = file_path.stat()
file_size = stat.st_size

range_header = request.headers.get("Range")
if not range_header:
    return FileResponse(file_path, media_type="application/octet-stream")

# 解析 Range: bytes=0-1023
try:
    ranges = range_header.strip().replace("bytes=", "").split("-")
    start = int(ranges[0]) if ranges[0] else 0
    end = int(ranges[1]) if len(ranges) > 1 and ranges[1] else file_size - 1
    end = min(end, file_size - 1)
    if start > end or start < 0:
        raise ValueError
except (ValueError, IndexError):
    raise HTTPException(416, headers={"Content-Range": f"bytes */{file_size}"})

content_length = end - start + 1
headers = {
    "Content-Range": f"bytes {start}-{end}/{file_size}",
    "Accept-Ranges": "bytes",
    "Content-Length": str(content_length),
    "Content-Type": "application/octet-stream",
}

async def chunk_generator():
    with open(file_path, "rb") as f:
        f.seek(start)
        remaining = content_length
        while remaining > 0:
            chunk_size = min(8192, remaining)
            chunk = f.read(chunk_size)
            if not chunk:
                break
            yield chunk
            remaining -= len(chunk)

return StreamingResponse(
    chunk_generator(),
    status_code=206,
    headers=headers,
)

注意 `request` 在函数签名中要显式声明

上面示例用了 request，但 FastAPI 不会自动注入，必须在函数参数里加上 request: Request，否则报错 NameError: name 'request' is not defined。这是新手最常漏掉的一处。

导入：from fastapi import Request
函数签名改为：async def download_file(filename: str, request: Request):
不加这句，request.headers.get("Range") 直接崩溃

生产环境要注意文件路径安全和并发读取

直接拼接 filename 到路径里有路径遍历风险（如传 ../../etc/passwd）。同时，每个请求都 open() 同一个大文件，在高并发下可能触发系统文件描述符耗尽或磁盘 I/O 瓶颈。

务必对 filename 做白名单校验或使用 pathlib.Path.resolve() 并检查是否在允许目录内
考虑加缓存层（如 nginx 静态服务 + X-Accel-Redirect）来卸载 Range 处理
若文件来自云存储，不能直接 seek()，得用分段下载 API（如 S3 的 get_object(Range=...)）并透传响应头

Range 支持看着只是加几行头，但边界判断、错误码、流控制、安全性，每一处都容易漏掉。尤其是 416 响应的 Content-Range 格式和 request: Request 的显式声明，上线前不测真实断点场景很容易以为“能跑”其实不可靠。

# nginx # 浏览器 # app # 字节 # ai # stream # 云存储 # 状态码 # red # fastapi # 封装 # Length # 并发 # 对象 # http # 不支持 # 的是 # 这是 # 大文件 # 看着 # 第一个 # 尤其是 # 多个 # 遍历 # 很容易

相关栏目：【网站优化151355 】【网络推广146373 】【网络技术251813 】【 AI营销90571 】