Python subprocess.Popen 怎样实时读取标准输出而不堵塞

用 subprocess.Popen 启动持续输出的命令时，想实时看到标准输出，关键不是简单写一行 proc.stdout.read()，而是同时排空 stdout 和 stderr 两条管道。下面这个模板让两个读取线程把日志放进 Queue，主线程负责展示、观察进程退出并检查返回码，避免某一条管道填满后把子进程卡住。

为什么只读 stdout 容易出现“卡住”

Popen 将输出接到 PIPE 后，数据会经过操作系统管道。父进程如果一直等待 stdout，而子进程把大量错误信息写入 stderr，stderr 的缓冲区可能先满，子进程便停在写操作上，父进程也就等不到新的 stdout。官方文档因此建议使用 communicate() 避免管道死锁；但它会把收集结果放在内存里，不适合无限或很大的实时日志。

实时消费时，第一步是明确三件事：子进程是否会主动刷新、两条流是否都有人读取、子进程退出后读取端是否能收到 EOF。下面的示例使用列表参数，不依赖 shell 拼接；其中 -u 只针对示例子进程，真实命令要使用自身支持的无缓冲或 flush 选项。

用两个读取线程同时排空 stdout 和 stderr

把读取工作放到独立线程，主线程就不会被某一行日志永久挡住；两条线程共享一个队列，消息里带上来源，后续既能统一显示，也能单独统计错误流。

import queue
import subprocess
import sys
import threading

def pump(stream, output_queue, channel):
    # readline 读到空字符串代表管道关闭；每行带来源，避免 stdout/stderr 混淆。
    for line in iter(stream.readline, ""):
        output_queue.put((channel, "line", line.rstrip("\n")))
    stream.close()
    output_queue.put((channel, "eof", None))

child_code = (
    "import sys, time; "
    "[print(f'progress {i}', flush=True) or time.sleep(0.2) for i in range(3)]"
)

proc = subprocess.Popen(
    [sys.executable, "-u", "-c", child_code],
    stdout=subprocess.PIPE,
    stderr=subprocess.PIPE,
    text=True,
    encoding="utf-8",
    bufsize=1,  # 这里只影响父进程的文本管道包装，不替子进程 flush。
)
events = queue.Queue()
threads = [
    threading.Thread(target=pump, args=(proc.stdout, events, "stdout"), daemon=True),
    threading.Thread(target=pump, args=(proc.stderr, events, "stderr"), daemon=True),
]
for thread in threads:
    # 两条流同时读取，避免只消费 stdout 造成另一条管道回压。
    thread.start()

open_streams = len(threads)
while open_streams or proc.poll() is None:
    try:
        channel, kind, payload = events.get(timeout=0.2)
    except queue.Empty:
        continue
    if kind == "line":
        print(f"[{channel}] {payload}")
    # EOF 是读取线程发出的关闭标记，不把它和业务日志内容混在一起。
    elif kind == "eof":
        open_streams -= 1

for thread in threads:
    thread.join()
returncode = proc.wait()
if returncode != 0:
    raise RuntimeError(f"子进程退出码为 {returncode}")

上面的关闭标记需要和代码严格对应：当前示例把空行过滤掉了，因此更稳妥的生产写法是让 pump 在循环结束后再放入一个特殊事件，而不是依赖普通日志内容。下面给出这个小修正，避免真实业务输出恰好包含空字符串时误判。

def pump(stream, output_queue, channel):
    # 先发送所有实际行，再发送唯一的 EOF 事件；EOF 不是业务日志。
    for line in iter(stream.readline, ""):
        output_queue.put((channel, "line", line.rstrip("\n")))
    stream.close()
    output_queue.put((channel, "eof", None))

子进程 flush、bufsize 和 readline 不是一回事

父进程设置 text=True 后得到文本流，bufsize=1 表示父进程侧的管道文件对象使用行缓冲语义；它不能强迫子进程把自己的输出立即交给管道。若子进程是 Python，可以使用 -u 或在 print 中显式 flush=True。如果子进程是其他语言，要查看该程序自己的 stdout 缓冲配置。

什么时候改用 communicate

如果输出量有限，而且只需要在命令结束后统一拿到 stdout/stderr，优先使用 proc.communicate()。需要超时控制时捕获 subprocess.TimeoutExpired，清理子进程后再次调用 communicate() 收尾；不要在超时后直接用 wait() 把管道处理丢开。对于持续日志、交互式命令或需要边收边显示的任务，使用上面的消费模型更合适。

相关问题

只需要 stdout，可以把 stderr 设成 DEVNULL 吗？

可以，但这会放弃错误日志。若错误信息对排查有价值，应该持续读取，或者用 stderr=subprocess.STDOUT 合并到 stdout 后统一消费。

为什么给 Popen 加 bufsize=1 仍然不实时？

因为它主要影响父进程打开的管道包装，子进程自己的缓冲仍然存在。先确认子进程是否 flush，再检查父进程是否逐行读取。

读取结束后为什么还要检查 returncode？

EOF 只表示输出流关闭，不代表任务成功。只有 returncode == 0 才能把这次执行视为正常完成；负值还可能表示 POSIX 信号终止。