Python subprocess.run timeout 后怎么终止子进程树

定时调用外部转换器时，最容易出现的故障是：父进程报了 TimeoutExpired，但真正干活的孙进程还在跑，临时目录和 CPU 也没有释放。根因不是把 timeout 调大，而是 subprocess.run() 没有给“整棵进程树”定义一个可管理的边界。

需要清理进程树时，使用 Popen 替代 run：POSIX 创建独立会话后用 os.killpg() 终止进程组，Windows 创建新进程组后按 Windows 信号语义降级处理；超时分支最后必须再次 communicate()。

先改用 Popen，给子进程单独建立会话

一次线上任务的时间线通常是：主程序启动转换器，转换器再启动压缩或解码 worker；等待超过 20 秒后，主程序捕获超时并返回，但 worker 继承的文件句柄仍然打开。此时杀掉一个 PID，只能说明父节点停止了，不能说明后代都停止。

在 Linux、macOS 等 POSIX 系统上，启动时设置 start_new_session=True，子进程会调用 setsid()，成为新会话的组长。随后可以把这个 PID 当作进程组 ID 使用。不要用线程环境下不安全的 preexec_fn 去手动调用 setsid()。

import os
import signal
import subprocess

# POSIX：让外部命令成为新会话的进程组组长
proc = subprocess.Popen(
    ["media-tool", "--input", "input.dat"],
    stdout=subprocess.PIPE,
    stderr=subprocess.PIPE,
    text=True,
    start_new_session=True,
)

这里没有使用 shell=True，参数以列表传入，避免额外的 shell 包装层改变进程关系。若业务确实需要 shell 语法，也要把“shell 进程”和它创建的后代一起纳入进程组设计。

超时后先杀进程组，再回收输出

关键顺序是“温和终止、等待、强制终止、回收”。communicate(timeout=...) 只负责等待并抛出 TimeoutExpired；捕获异常后先发 SIGTERM，给程序清理临时文件的机会；如果它仍未退出，再发 SIGKILL，最后无论哪种结果都调用一次不带 timeout 的 communicate()。

def run_with_tree_timeout(command: list[str], timeout: float) -> tuple[int, str, str]:
    # 独立进程组让清理范围覆盖命令启动的后代
    proc = subprocess.Popen(
        command,
        stdout=subprocess.PIPE,
        stderr=subprocess.PIPE,
        text=True,
        start_new_session=True,
    )
    try:
        # 正常路径一次性读取输出并等待退出
        stdout, stderr = proc.communicate(timeout=timeout)
        return proc.returncode, stdout, stderr
    except subprocess.TimeoutExpired:
        # 先通知整组进程优雅退出，而不是只杀父 PID
        os.killpg(proc.pid, signal.SIGTERM)
        try:
            # 给子进程一个有限的清理窗口
            stdout, stderr = proc.communicate(timeout=2)
        except subprocess.TimeoutExpired:
            # 清理窗口耗尽后强制结束整组进程
            os.killpg(proc.pid, signal.SIGKILL)
            stdout, stderr = proc.communicate()
        raise RuntimeError(f"command timed out: {command!r}; stderr={stderr[-500:]}")

生产代码还应把发送信号包在对 ProcessLookupError 的处理里，因为进程可能恰好在信号前自行退出。超时异常中的输出可以先保存到日志，但大而无界的 stdout/stderr 不适合无限制地放进内存。

Windows 不用 killpg，改用新进程组

Windows 没有 POSIX 的 killpg 语义。可以使用 creationflags=subprocess.CREATE_NEW_PROCESS_GROUP 创建新的控制台进程组，超时后尝试发送 CTRL_BREAK_EVENT；若程序不响应，再调用 terminate() 或 kill()。这套方案依赖目标程序是否连接到可接收控制事件的控制台，不能把 SIGTERM 的行为想当然地套过来。

跨平台封装时，建议按 os.name 分支实现两个清理器，并统一返回“是否超时、退出码、截断后的 stderr”。不要在一个函数里无条件调用 os.killpg，也不要把 Windows 的强制终止误称为优雅关闭。

常见问题：timeout、shell 和 PIPE 的边界

为什么不直接用 subprocess.run(timeout=20)？

它适合只关心一个直接子进程的短命令。需要控制进程组、分阶段终止或保留 Popen 句柄时，应改用 Popen 加 communicate。

调用 proc.kill() 后还要 communicate 吗？

要。kill() 只改变进程状态，管道读取和父进程回收仍需要完成；否则可能残留句柄、输出未收尽或形成僵尸进程。

shell=True 能解决子进程树清理吗？

不能。它通常只增加一个 shell 层，反而让终止范围更难判断。能用参数列表表达命令时，优先保持 shell=False。

排查这类问题时，最后核对四件事：启动是否建立了独立边界、终止是否覆盖目标进程组、超时后是否再次回收输出、Windows 与 POSIX 是否走了不同实现。这样处理，timeout 才真正对应一次可收尾的任务失败。