Python异步上传大文件技巧

本文深入解析了Python中异步上传大文件的正确实践，直击aiohttp直接传入同步文件句柄导致内存爆满的核心陷阱，并给出基于aiofiles的异步分块读取生成器方案，配合进度回调、取消支持及关键服务端（Nginx、FastAPI等）配置调优，手把手教你实现真正高效、可控、生产可用的端到端流式上传，避免“卡在最后1%”、413错误或隐性阻塞等常见坑。

为什么 aiohttp 的 post() 直接传 open() 文件句柄会爆内存

因为默认行为是把整个文件读进内存再发出去。哪怕你写的是 async with aiohttp.ClientSession() as session: await session.post(url, data=open("big.zip", "rb"))，aiohttp 内部仍会调用 .read() 把全部内容加载为 bytes——这对几百 MB 的文件就是灾难。

真正流式上传必须绕过这个自动读取逻辑，手动控制分块读取 + 分块发送。

• 别用 data=open(...)，改用 data=AsyncReader 或生成器
• 确保文件以二进制模式打开："rb"，且不带 buffering=0（会破坏 asyncio 兼容性）
• 如果服务端不支持分块传输（如某些 Nginx 默认配置），即使客户端流式发了，也可能被代理缓冲住，表现为“卡在最后 1%”

用 async for + StreamReader 实现可控分块读取

核心是自己构造一个异步可迭代对象，每次 yield 一块数据（比如 64KB），让 aiohttp 边读边发，而不是等全读完。

async def file_reader(file_path, chunk_size=65536):
    async with aiofiles.open(file_path, "rb") as f:
        while True:
            chunk = await f.read(chunk_size)
            if not chunk:
                break
            yield chunk
<h1>使用时传给 data 参数</h1><p>async with aiohttp.ClientSession() as session:
async with session.post(url, data=file_reader("huge.bin")) as resp:
print(resp.status)
</p>

• aiofiles 是必须的：标准 open() 是同步阻塞的，会拖垮整个 event loop
• chunk_size 建议设为 2¹⁶（64KB）左右：太小增加系统调用开销，太大仍可能挤占内存
• 不要在生成器里做耗时操作（如解密、压缩），否则会阻塞 event loop

上传时带进度回调和取消支持怎么加

aiohttp 本身不提供上传进度钩子，得靠包装 data 迭代器来实现计数和中断判断。

class ProgressReader:
    def __init__(self, file_path, chunk_size=65536, on_progress=None):
        self.file_path = file_path
        self.chunk_size = chunk_size
        self.on_progress = on_progress
        self.total_sent = 0
        self._cancelled = False
<pre class="brush:php;toolbar:false"><code>def cancel(self):
    self._cancelled = True

async def __aiter__(self):
    async with aiofiles.open(self.file_path, "rb") as f:
        while not self._cancelled:
            chunk = await f.read(self.chunk_size)
            if not chunk:
                break
            self.total_sent += len(chunk)
            if self.on_progress:
                self.on_progress(self.total_sent)
            yield chunk</code>

• 在 on_progress 回调里可以更新 UI、打印日志，或检查是否该中止（比如用户点了“取消”）
• 取消不是立刻生效的：当前 chunk 发完才会退出循环，所以响应有轻微延迟
• 如果需要更精确的中断（比如正在发一个大 chunk 时就停），得用 asyncio.CancelledError 配合 try/except 捕获，但代价是代码复杂度上升

服务端没配好会导致流式上传失败的典型表现

客户端流式发得再稳，遇到以下情况也会卡住、超时或返回 413/400：

• Nginx 默认 client_max_body_size 1m：大文件直接被拦在网关，返回 413；要改成 0（不限）或足够大的值
• FastAPI/Starlette 默认限制 max_upload_size：需显式配置 UploadFile 的 size_limit 参数或用 StreamingResponse 接收
• 某些云函数（如 AWS Lambda）有 6MB 请求体硬限制，根本不支持流式上传，必须换用预签名 URL + S3 直传
• 后端框架若用 request.body 一次性读取，等于又把流变回内存加载，白忙活

真正端到端流式，客户端发得动，服务端也得接得住——光改 Python 代码不够，Nginx、WAF、后端框架、存储层都得对齐配置。

到这里，我们也就讲完了《Python异步上传大文件技巧》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！