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
示例片段：
基于 AIOZ Stream API 的免费音频上传技能，通过三步流程（Create → Upload Part → Complete）将本地音频文件上传至 AIOZ 流媒体平台。支持默认快速上传方式，使用默认编码配置，上传完成后返回 HLS 流媒体播放链接。使用 API Key (stream-publ...)进行认证。
@app.get("/download/{filename}")
async def download_file(filename: str):
file_path = Path("uploads") / filename
if not file_path.is_file():
raise HTTPException(404)
<pre class='brush:python;toolbar:false;'>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 的显式声明，上线前不测真实断点场景很容易以为“能跑”其实不可靠。
