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 的显式声明，上线前不测真实断点场景很容易以为“能跑”其实不可靠。