Python subprocess.run 超时后如何区分子进程已退出还是仍存活

调用 subprocess.run() 时，如果超过 timeout，很多人会在 except subprocess.TimeoutExpired 里继续猜测子进程是不是还活着。这个猜测对 run() 并不成立：Python 会先终止并等待它启动的子进程，再把超时异常重新抛出。因此，run() 适合判断“这次执行是否在时限内完成”，不适合在超时异常里观察子进程的瞬时存活状态。

先看清 subprocess.run 的三条结果路径

没有超时且命令成功时，run() 返回 CompletedProcess，其中的 returncode 通常为 0。命令执行完但返回非零码时，只有传入 check=True 才会抛出 CalledProcessError。超过等待时间则抛出 TimeoutExpired。

关键点在于实现语义：run() 内部使用 Popen.communicate()，超时后会杀掉子进程并等待，随后重新抛出 TimeoutExpired。所以异常表示“没有在规定时间内完成”，而不是“捕获异常的这一刻仍然有一个直接子进程可供查询”。

import subprocess

try:
    # 只关心命令能否在 3 秒内完成，参数用列表避免额外 shell 解析。
    result = subprocess.run(
        ["python", "worker.py"],
        capture_output=True,
        text=True,
        timeout=3,
        check=True,
    )
    print("完成：", result.returncode)
except subprocess.TimeoutExpired as exc:
    # run() 的超时异常用于记录超时，不用于判断直接子进程当前是否存活。
    print("执行超过 3 秒：", exc.timeout)
except subprocess.CalledProcessError as exc:
    # 命令已经退出，但退出码不是 0；这和超时是两种故障。
    print("命令失败：", exc.returncode)

需要判断存活状态时改用 Popen.poll

Popen.returncode 初始为 None，只有 poll()、wait() 或 communicate() 检测到进程结束后才会写入退出码。poll() 不等待：返回 None 表示截至这次检查仍未结束，返回整数表示已经退出。它是一个瞬时观察，不是对未来状态的承诺。

下面的写法保留了超时点的可观察性。communicate() 超时后先用 poll() 查看最近状态；如果仍返回 None，再终止子进程。即使在两个调用之间它刚好退出，也不会重复假设其状态。

import subprocess

proc = subprocess.Popen(
    ["python", "worker.py"],
    stdout=subprocess.PIPE,
    stderr=subprocess.PIPE,
    text=True,
)

try:
    # communicate 同时读取输出并等待，避免 stdout/stderr 管道被写满而互相等待。
    stdout, stderr = proc.communicate(timeout=3)
    print("按时结束：", proc.returncode)
except subprocess.TimeoutExpired:
    # poll 不阻塞；None 只代表本次检查时仍未结束。
    state = proc.poll()
    if state is None:
        # 仍在运行才执行强制清理，避免误杀已经自然退出的子进程。
        proc.kill()
        timed_out_alive = True
    else:
        # 进程在超时边界附近自然退出，保留它的退出码。
        timed_out_alive = False

    # 超时后的收尾继续用 communicate，既排空管道也更新 returncode。
    stdout, stderr = proc.communicate()
    print("超时前后是否观察到仍存活：", timed_out_alive)
    print("最终退出码：", proc.returncode)

回收顺序比判断变量更重要

如果创建了 stdout=PIPE 或 stderr=PIPE，不要在超时分支里只调用 wait() 或直接读取某一个管道。子进程可能已经写满另一个管道，导致父进程和子进程互相等待。官方建议在超时后终止子进程，再次调用 communicate() 完成读取；这也是让 returncode 稳定落地的收尾动作。

还要注意“子进程”与“进程树”不是同一范围。kill() 针对的是 Popen 创建的那个进程；如果它又启动了孙进程，是否一并终止取决于平台和进程组设计。生产任务若需要整组取消，应单独设计进程组或作业管理，不要把一次 poll() 的结果当成整棵进程树的结论。

常见问题

TimeoutExpired 里能直接读取子进程的 returncode 吗？

对 run() 来说没有可供调用方持有的 Popen 对象。要查询退出码或存活状态，改用 Popen 并在超时后调用 poll()。

poll() 返回 None 就一定还会继续运行吗？

不一定。它只反映调用瞬间的最近检查结果，进程可能在返回后立刻退出，所以后续仍要执行一次安全收尾。

为什么超时后还要再次 communicate？

它负责排空已经打开的输出管道并更新最终退出码；只杀进程而不收尾，容易遗留未读输出、资源和不完整状态。