Python异步调用外部命令的踩坑实录

1. 阻塞事件循环：别在async函数里用subprocess.run()

许多开发者习惯使用subprocess.run()，这是一个同步阻塞调用。如果在async函数中直接调用它，会阻塞整个事件循环，导致FastAPI等其他协程无法执行。正确的做法是使用asyncio.create_subprocess_exec()来创建异步子进程。

async def process_video(path):
    # ❌ 错误示范：阻塞整个事件循环
    result = subprocess.run(["ffmpeg", "-i", path, "output.mp4"], capture_output=True)
    return result.stdout

async def process_video(path):
    # ✅ 正确做法：异步等待子进程
    proc = await asyncio.create_subprocess_exec(
        "ffmpeg", "-i", path, "output.mp4",
        stdout=asyncio.subprocess.PIPE,
        stderr=asyncio.subprocess.PIPE
    )
    stdout, stderr = await proc.communicate()
    return stdout

2. 管道死锁：必须消费stdout和stderr

当设置stdout=PIPE时，如果忘记读取输出，操作系统管道缓冲区（通常64KB）写满后，子进程会阻塞在write()上，而父进程的await永远无法返回，导致死锁。即使只调用wait()而不读取输出也会发生这种情况。

解决方案是始终使用communicate()同时读取stdout和stderr。如果不需要输出，可以将输出重定向到DEVNULL。

# ❌ 错误示范：可能导致死锁
async def run_tool(cmd):
    proc = await asyncio.create_subprocess_exec(*cmd, stdout=asyncio.subprocess.PIPE)
    await proc.wait()  # 子进程可能因管道满而阻塞，这里永远等不到返回
    return proc.returncode

# ✅ 正确做法：同时消费两个管道
async def run_tool(cmd):
    proc = await asyncio.create_subprocess_exec(
        *cmd,
        stdout=asyncio.subprocess.PIPE,
        stderr=asyncio.subprocess.PIPE
    )
    stdout, stderr = await proc.communicate()
    return proc.returncode, stdout, stderr

# 如果不需要输出，可以重定向到DEVNULL
proc = await asyncio.create_subprocess_exec(
    *cmd,
    stdout=asyncio.subprocess.DEVNULL,
    stderr=asyncio.subprocess.DEVNULL
)

3. 文件描述符耗尽：使用Semaphore控制并发

每个子进程至少占用3个文件描述符（stdin、stdout、stderr）。如果大量并发子进程同时运行，可能会耗尽系统的文件描述符限制（通常默认为1024），抛出OSError: [Errno 24] Too many open files。

解决方法是使用asyncio.Semaphore限制并发子进程的数量。

# 1. 查看当前限制
import resource
print(resource.getrlimit(resource.RLIMIT_NOFILE))  # 通常1024

# 2. 用Semaphore控制并发数
sem = asyncio.Semaphore(10)  # 最多10个并发子进程

async def run_with_limit(cmd):
    async with sem:
        proc = await asyncio.create_subprocess_exec(
            *cmd,
            stdout=asyncio.subprocess.PIPE,
            stderr=asyncio.subprocess.PIPE
        )
        stdout, stderr = await proc.communicate()
        return proc.returncode, stdout

# 3. 或者临时提高限制（需要权限）
# resource.setrlimit(resource.RLIMIT_NOFILE, (65536, 65536))

4. 子进程超时与僵死处理

某些命令行工具（如wkhtmltopdf）偶尔会卡死。在Python 3.11之前，communicate()没有超时参数，直接await可能永远等待。需要使用asyncio.wait_for()设置超时，并在超时时调用kill()和wait()防止子进程变成僵尸进程。

# ❌ 可能永远卡住
stdout, stderr = await proc.communicate()

# ✅ 用wait_for加超时
try:
    stdout, stderr = await asyncio.wait_for(proc.communicate(), timeout=30.0)
except asyncio.TimeoutError:
    proc.kill()  # 发SIGKILL
    await proc.wait()  # 等待进程回收，避免僵尸进程
    raise

更干净的做法是创建子进程时指定新的进程组，超时后杀整个进程组。

import os
import signal

# 创建子进程时指定新的进程组
proc = await asyncio.create_subprocess_exec(
    *cmd,
    stdout=asyncio.subprocess.PIPE,
    stderr=asyncio.subprocess.PIPE,
    preexec_fn=os.setsid  # 新进程组
)

# 超时后杀整个进程组
try:
    stdout, stderr = await asyncio.wait_for(proc.communicate(), timeout=30.0)
except asyncio.TimeoutError:
    os.killpg(os.getpgid(proc.pid), signal.SIGKILL)
    await proc.wait()

5. Windows上的兼容性地狱

Windows上create_subprocess_exec不支持preexec_fn参数，也没有进程组概念。Windows上杀进程要用proc.terminate()而不是发信号。此外，Windows上stdout默认是系统编码GBK，需要特殊处理。

import sys

async def run_cross_platform(cmd):
    kwargs = {
        "stdout": asyncio.subprocess.PIPE,
        "stderr": asyncio.subprocess.PIPE,
    }
    
    if sys.platform != "win32":
        kwargs["preexec_fn"] = os.setsid
    
    proc = await asyncio.create_subprocess_exec(*cmd, **kwargs)
    
    try:
        stdout, stderr = await asyncio.wait_for(proc.communicate(), timeout=30)
    except asyncio.TimeoutError:
        if sys.platform == "win32":
            proc.terminate()
        else:
            os.killpg(os.getpgid(proc.pid), signal.SIGKILL)
        await proc.wait()
        raise
    
    # Windows编码处理
    if sys.platform == "win32":
        stdout = stdout.decode("gbk", errors="replace")
        stderr = stderr.decode("gbk", errors="replace")
    
    return stdout, stderr

总结

• 同步subprocess阻塞事件循环的解法是用create_subprocess_exec
• 管道未消费导致死锁的解法是communicate()或DEVNULL
• fd耗尽Too many open files的解法是Semaphore控制并发
• 子进程僵死永久挂起的解法是wait_for超时加kill加wait
• Windows兼容性问题需使用条件分支加terminate

以上就是Python异步调用外部命令的踩坑实录的详细内容，更多关于Python异步编程、subprocess和asyncio的资料请关注本站其它相关文章！