Python subprocess 超时后怎样终止并读取输出

我在处理外部命令时遇到过一个很容易误判的场景：Popen.communicate(timeout=...) 抛出了超时异常，主程序已经进入异常分支，但被启动的子进程还在占着资源。更麻烦的是，命令在超时前已经写出的输出也不能随手丢掉。

这类问题的稳定处理方式是：先用 PIPE 接住需要保留的输出，捕获 TimeoutExpired 后显式调用 kill()，然后再次调用不带输入参数的 communicate() 完成管道排空和退出码回收。Python 官方地址：https://docs.python.org/3.14/library/subprocess.html

超时只代表等待窗口结束，不代表子进程已经被杀掉。对 Popen.communicate() 来说，终止子进程和读完输出是两个动作；异常分支里少了第二次 communicate()，就可能留下未回收的进程或丢失尾部输出。

我第一次踩坑时，误把超时当成了终止

当外部命令偶尔卡住时，我最初只写了一个 except TimeoutExpired，记录日志后就返回。这样做的表面结果是接口很快返回，实际却把清理责任推迟给了操作系统和对象析构：子进程可能继续运行，管道也可能继续占用文件描述符。

官方文档对 Popen.communicate(timeout) 的约定很明确：超时会抛出 TimeoutExpired，但子进程不会因为这个异常自动被杀掉。正确的收尾是杀掉子进程，再用额外一次 communicate() 处理管道并填充 returncode。这里不要再调用 wait()，因为超时后的通信收尾已经承担了这个职责。

先把输出管道和文本编码设好

想在超时后拿到输出，创建进程时就要把 stdout 和 stderr 指向 PIPE。如果希望示例直接得到字符串，可以使用 text=True 并明确 encoding。没有设置对应的管道，后面的结果自然只能是 None。

from subprocess import PIPE, Popen

command = ["python", "worker.py", "--mode", "export"]
proc = Popen(
    command,
    stdin=PIPE,
    stdout=PIPE,
    stderr=PIPE,
    text=True,
    encoding="utf-8",
)

这里使用参数列表而不是拼接命令字符串，边界更清楚，也不会因为参数中出现空格而依赖 shell 的再次解析。stdin=PIPE 只有在确实要向子进程写入内容时才需要；如果不发送输入，可以去掉它，但两条输出管道要保留。

捕获 TimeoutExpired 后，先终止再收尾

关键代码可以保持很短，但顺序不能调换。第一次 communicate(timeout=...) 负责在规定时间内等待；超时后调用 kill() 结束子进程；第二次 communicate() 不再传入 input，只负责把管道剩余数据读完并更新退出码。

from subprocess import PIPE, Popen, TimeoutExpired

def run_with_timeout(command: list[str], timeout: float) -> tuple[int, str, str, bool]:
    # 用文本管道接住标准输出和标准错误，便于超时后记录诊断信息。
    proc = Popen(
        command,
        stdout=PIPE,
        stderr=PIPE,
        text=True,
        encoding="utf-8",
    )

    try:
        # 正常完成时，这里同时等待进程结束并返回两路输出。
        stdout, stderr = proc.communicate(timeout=timeout)
        return proc.returncode, stdout, stderr, False
    except TimeoutExpired as exc:
        # 超时不等于子进程已退出，先明确终止它。
        proc.kill()
        # 不再传入 input；第二次 communicate 负责排空管道并设置 returncode。
        stdout, stderr = proc.communicate()

        # 某些场景下异常对象保留了已读到的输出，最终结果以收尾调用为准。
        if not stdout and exc.stdout:
            stdout = exc.stdout.decode("utf-8", errors="replace") if isinstance(exc.stdout, bytes) else exc.stdout
        if not stderr and exc.stderr:
            stderr = exc.stderr.decode("utf-8", errors="replace") if isinstance(exc.stderr, bytes) else exc.stderr
        return proc.returncode, stdout, stderr, True

正常完成和超时完成都返回相同的四元组，调用方可以把 timed_out 单独写入日志或指标。超时分支中保留异常对象里的输出只是兜底；在常见的文本模式下，第二次 communicate() 会给出可直接记录的字符串。

再次 communicate 怎样拿回超时前后的输出

communicate() 的结果是 (stdout_data, stderr_data)。只要提前打开对应的 PIPE，超时前已经读入缓冲区的内容不会因为捕获异常而自动消失；重试通信也不会丢失输出。需要注意的是，超时之后不要再次给 communicate() 传入输入数据，输入的后续行为没有稳定保证。

如果你没有设置 text=True，结果通常是字节串；这时可以在收尾后统一解码。生产代码还要决定遇到坏字节时是报错、替换还是记录原始字节，不要把编码错误和超时错误混为一谈。

生产环境还要检查四个边界

第一，输出量是否有上限。 communicate() 会把数据缓存在内存里，不能用于无限增长的输出。大量日志应改为文件、轮转管道或专门的异步消费方案，不能只把超时时间调大。

第二，是否真的只启动了一个进程。 如果通过 shell=True 启动了 shell 命令，proc.kill() 主要针对的是被创建的 shell 进程，命令内部再派生的进程可能需要额外的进程组策略。没有 shell 需求时，优先传入参数列表并保持 shell=False。

第三，终止方式是否符合业务语义。 terminate() 在 POSIX 上发送 SIGTERM，适合给进程一个清理机会；kill() 在 POSIX 上发送 SIGKILL，更强硬。标题所说的“超时后终止”若强调确定性收尾，可以使用 kill()；若外部程序支持优雅退出，可先尝试 terminate()，再设置一个很短的二次等待边界。

第四，退出码要独立记录。 被杀掉的进程不是“业务成功”，即使标准输出里有一段看似完整的结果，也应该把 returncode 和 timed_out 一起交给上层判断。

一张表记住处理顺序

我的结论：把“杀进程”和“拿输出”写成一个不可拆的动作

对我来说，最可靠的判断标准不是“异常有没有被捕获”，而是异常分支结束时是否同时满足三个条件：子进程已经结束、输出管道已经收尾、退出码已经被记录。只要这三个动作分散在不同层里，后续维护就很容易遗漏其中一个。

这个模式适合调用有限时长的编译、导出、转换或脚本任务；它不适合无限输出或复杂子进程树。如果任务本身是异步调度、需要并发取消或要管理整组进程，就应该把超时边界上移到任务管理器，并为进程组、日志流和取消传播单独设计。

相关问题

• TimeoutExpired 之后可以直接调用 wait() 吗？ 不建议。对于 communicate 超时，按官方约定使用额外一次 communicate 完成管道处理和退出码填充。
• 为什么 stdout 或 stderr 是 None？ 创建 Popen 时没有为对应流设置 PIPE，或者把该流重定向到了 DEVNULL。
• 超时后还能保留部分输出吗？ 可以，只要预先捕获输出；异常对象可能有已读内容，最终应以终止后的 communicate 收尾结果为主。
• 什么时候应该改用 subprocess.run？ 如果不需要持有 Popen 对象和自定义清理，run 的 timeout 参数更简洁；需要精细控制终止与收尾时再使用 Popen。