Python subprocess 超时之后，子进程真的停止了吗？

一次命令调用抛出了 TimeoutExpired，调用方记录“执行超时”并返回。几秒后，输出文件却出现了。这不一定是日志乱序，也可能是调用方停止等待时，任务仍在运行。如果把超时直接等同于取消，随后重试还可能让同一份工作执行两次。

Python 标准库里两个常见入口对此有不同约定：subprocess.run 的 timeout 分支会终止并等待直接子进程；Popen.communicate 的 timeout 分支不会自动杀死子进程。本文用一个本地短实验分别观察这两种行为，再验证显式清理的方法。实验只创建直接 Python 子进程，不调用 shell、不创建后代进程，不推导进程树清理能力。

一、先区分等待超时与进程退出

communicate 同时承担与子进程交换输入、收集输出及等待结束的工作。给它设置 timeout，是为这次通信等待设置期限。等待超过期限会抛异常，但进程句柄仍属于调用方，后续怎样处理要由调用方决定。捕获异常后直接返回，可能留下继续工作的进程。

run 是更高一层的便捷接口，内部创建 Popen 并调用 communicate。它遇到 TimeoutExpired 时会执行 kill，再完成必要的等待或输出收集，然后重新抛出异常。因此，run 的调用者接到这个超时异常时，不能照搬 communicate 的规则，认为直接子进程仍在运行。

两者也都不能把“已经做过的事”撤回。即使 run 结束了进程，超时前发出的请求、写入的数据、提交的事务也可能已经生效。结束进程与业务取消是两个独立问题，这正是任务重试必须考虑幂等性的原因。

这次实验采用三个判据：超时处理处的 poll 是否为 None；超时之后放行，子进程是否还能写出完成标记；显式 kill 后，是否已取得退出状态并收集剩余输出。仅看异常类型或某行日志，都不足以覆盖这些判断。

二、用文件握手建立可观察的时序

子进程先打印 READY，刷新输出，再写就绪文件。随后它只轮询放行文件，最多等五秒；看到放行文件才写完成标记并打印 DONE。父进程确认就绪后，才进入二百毫秒的超时等待。这样能把解释器启动时间与实验观察窗口分开，减少机器负载对结论的干扰。

第一组使用 run。由于它不返回超时时的 Popen 对象，实验用 unittest.mock.patch 暂时包装 Popen 构造入口：仍调用真实构造器，只保存对象并等待就绪。run、communicate 和 kill 的实现都没有替换。包装只在这一小段单线程实验生效，不是推荐的生产调用方式，也意味着这组计时不包含握手准备。

第二组直接使用 Popen。communicate 超时后检查进程仍在运行，然后写放行文件并再次 communicate，验证原来的那个子进程能完成工作。第三组则在同样的超时之后显式 kill，再 communicate，验证回收路径。

目录由 TemporaryDirectory 隔离，程序只通过自己持有的 Popen 对象结束进程，没有按名字查杀、扫描进程或向陌生 PID 发信号。所有创建成功的对象都进入 finally 清理。子进程也有五秒自限，避免示例中的等待逻辑无限挂起；这项自限不替代父进程的回收责任。

三、完整代码：三个分支放在一起跑

将以下完整代码保存为 subprocess-timeout-demo.py，使用 Python 3.12 执行命令 python subprocess-timeout-demo.py。只需要标准库，无须联网、安装依赖或管理员权限。代码采用参数列表，保持默认 shell=False，并使用 sys.executable 启动当前解释器。

"""Safe, standard-library experiment: direct children only, no shell."""
import os
import platform
from pathlib import Path
import subprocess
import sys
import tempfile
import time
from unittest.mock import patch


WORKER = r"""
from pathlib import Path
import sys
import time
root = Path(sys.argv[1])
print('READY', flush=True)
(root / 'ready').write_text('ready', encoding='utf-8')
deadline = time.monotonic() + 5
while not (root / 'release').exists():
    if time.monotonic() >= deadline:
        raise SystemExit(3)
    time.sleep(0.01)
(root / 'done').write_text('done', encoding='utf-8')
print('DONE', flush=True)
"""
REAL_POPEN = subprocess.Popen


def command(root):
    return [sys.executable, '-I', '-u', '-c', WORKER, str(root)]


def ready(proc, root):
    deadline = time.monotonic() + 2
    while not (root / 'ready').exists():
        if proc.poll() is not None:
            raise RuntimeError('worker exited before ready')
        if time.monotonic() >= deadline:
            raise TimeoutError('worker did not become ready')
        time.sleep(0.01)


def cleanup(proc):
    if proc.poll() is None:
        proc.kill()
    proc.communicate(timeout=2)
    assert proc.returncode is not None


def run_case(root):
    children = []

    def start(*args, **kwargs):
        proc = REAL_POPEN(*args, **kwargs)
        children.append(proc)
        ready(proc, root)
        return proc

    timed_out = False
    try:
        # A local spy keeps the real process object; run itself is unchanged.
        with patch.object(subprocess, 'Popen', side_effect=start):
            try:
                subprocess.run(command(root), stdout=subprocess.PIPE,
                               stderr=subprocess.PIPE, timeout=0.20)
            except subprocess.TimeoutExpired:
                timed_out = True
        assert timed_out and len(children) == 1
        proc = children[0]
        assert proc.poll() is not None
        assert not (root / 'done').exists()
        print('run: timeout=True, reaped=True, done=False')
    finally:
        for proc in children:
            cleanup(proc)


def communicate_case(root, release):
    proc = REAL_POPEN(command(root), stdout=subprocess.PIPE,
                      stderr=subprocess.PIPE)
    try:
        ready(proc, root)
        try:
            proc.communicate(timeout=0.20)
        except subprocess.TimeoutExpired as exc:
            partial_available = exc.output is not None
            if partial_available:
                assert exc.output.splitlines() == [b'READY']
        else:
            raise AssertionError('expected TimeoutExpired')
        assert proc.poll() is None
        print('communicate: timeout=True, alive=True, '
              f'partial_available={partial_available}')
        if release:
            (root / 'release').write_text('go', encoding='utf-8')
        else:
            proc.kill()
        output, errors = proc.communicate(timeout=2)
        assert output.splitlines() == ([b'READY', b'DONE'] if release
                                       else [b'READY'])
        assert errors == b'' and proc.poll() is not None
        assert (root / 'done').exists() == release
        if release:
            assert proc.returncode == 0
            print('release: output=READY|DONE, done=True, returncode=0')
        else:
            assert proc.returncode != 0
            print('kill: reaped=True, done=False, output=READY')
    finally:
        cleanup(proc)


def main():
    print(f'Python {platform.python_version()} | {platform.system()} '
          f'{platform.release()} | os.name={os.name}')
    with tempfile.TemporaryDirectory(prefix='timeout-demo-') as folder:
        base = Path(folder)
        for name in ('run', 'resume', 'kill'):
            (base / name).mkdir()
        run_case(base / 'run')
        communicate_case(base / 'resume', release=True)
        communicate_case(base / 'kill', release=False)
    print('PASS: 3 cases; all created direct children reaped')


if __name__ == '__main__':
    main()

这里的 cleanup 先检查退出状态，仅在仍运行时调用 kill，随后 communicate 收集输出并等待回收。它会被 finally 调用，即使前面的断言失败也会执行。程序没有用 Popen 上下文管理器代替取消逻辑，因为上下文退出时的等待本身不能表达“超时后应该终止”。

代码不要求强制结束的返回码等于某个固定数字。Windows 和 POSIX 对退出状态的表达不同，实验只检查已经结束且不是正常成功；放行分支才要求返回码为零。输出用 splitlines 比较，兼容常见换行差异，也不启用可能受区域设置影响的文本解码。

四、本机实测输出与逐项解释

本次在二〇二六年十一月五日使用 Windows 11、Python 3.12.14 实际执行。正式核验连续运行三次，每次都通过三个分支，标准错误为空，标准输出一致；最后一轮核验的用时另保存在验证记录中。下面完整输出来自实际运行，只将文本行结束符统一保存为换行，没有替换数值或编造平台信息。

Python 3.12.14 | Windows 11 | os.name=nt
run: timeout=True, reaped=True, done=False
communicate: timeout=True, alive=True, partial_available=False
release: output=READY|DONE, done=True, returncode=0
communicate: timeout=True, alive=True, partial_available=False
kill: reaped=True, done=False, output=READY
PASS: 3 cases; all created direct children reaped

第一行后的 run 结果表明：超时确实发生；进入异常处理后的检查阶段，真实进程对象已能取得退出状态；完成标记没有产生。reaped 是实验给这一状态起的输出名，不是 subprocess 的属性。它结合 run 的清理路径说明本次直接子进程已终止并被等待回收。

接下来的 alive=True 是在 communicate 超时后立即检查 poll 的结果。随后 release 一行给出更强的证据：没有新建进程，原来的子进程接收放行信号，继续写文件并输出 DONE，以零退出。它直接验证了“抛出超时异常之后仍能执行动作”，而不只是某一瞬间看起来存活。

第三组先得到同样的存活观察，再 kill 并 communicate。最终只读到 READY，没有完成标记，退出状态已收集。这说明需要取消工作时，显式结束和随后回收是两个必须衔接的步骤；kill 发出请求后就立刻丢掉句柄，会失去最后的清理确认。

五、超时异常中的输出也有边界

输出里的 partial_available=False 很容易引出另一个误判：子进程是不是根本没打印？本例打印并刷新发生在就绪文件之前，因此父进程确认就绪时，READY 已经写入管道。这里的 False 只说明本次 TimeoutExpired.output 没有返回那部分数据。

本机安装的 subprocess 实现中，Windows 的 communicate 使用后台读取线程收集管道内容；等待线程超时并不保证把当时读到的内容交给异常。本次实测正好得到 None。随后再次 communicate，放行分支仍获得完整 READY 与 DONE，结束分支也能获得 READY。

所以代码允许异常中的部分输出缺失；有数据时才检查内容，并最终核对第二次 communicate 的完整输出。不要把异常 output 是否为空当作进程存活检测，也不要把异常里的一段内容直接拼到重试 communicate 的结果前面，否则可能重复记录。这个输出细节只报告本次 Windows 结果，其他平台需要重新运行确认。

六、放到生产调用时怎样收口

如果只需要执行一个有界命令并获得结果，优先评估 run 是否满足需求。timeout 不是整个系统的绝对截止时间：进程创建阶段在一些系统上不可被这一机制打断，超时后的结束、等待和输出处理也需要时间。不能把二百毫秒配置解释成函数必定在二百毫秒内返回。

如果业务需要流式处理、分阶段交互或保留句柄，就明确承担 Popen 生命周期。捕获 communicate 超时后，应按业务选择继续等待、发出协作取消，或结束进程；选择结束时，再调用 communicate 或适当的等待流程收尾。本例中固定的清理预算用于小型本地实验，真实服务应设置与任务特征匹配的预算并暴露清理失败，不能无限吞掉异常。

跨平台还有一个容易混淆的地方：POSIX 上 kill 通常对应 SIGKILL，terminate 通常对应 SIGTERM；Windows 上二者在这里都通过终止进程机制工作，不能把 terminate 的名字理解为一定给程序机会保存状态。需要可靠收尾时，应设计任务能理解的取消协议，并定义迟迟不退出时的升级策略。

communicate 会把捕获输出收集到内存。本例只有两行输出，所以 PIPE 合理；不受控的大日志应采用文件或有容量约束的消费方案。也不要改成先 wait、后读 PIPE：子进程可能因为管道已满无法结束，父进程又在等待退出。超时处理、输出消费和内存上限应该一起设计。

七、把实验结论限制在证据之内

poll 返回值是一次状态观察，不是未来承诺；进程可以紧接着自然退出。本例依靠放行后产生的新标记补上因果证据，同时用 finally 覆盖每条退出路径。若机器过载导致就绪等待失败，程序会报错并尝试清理，不会打印一份伪造的成功结果。

这里验证的是父进程直接创建的 Python 子进程。被调用程序若再启动其他进程，尤其通过 shell、守护化或其他方式延长生命周期，本文没有验证它们如何退出，也不承诺 kill 一个直接子进程能清理整棵进程树。真实任务具有这类结构时，需要单独设计和验证所属平台的监管机制。

代码按跨平台标准库接口编写，但这次只在明确列出的 Windows 环境执行，不能把它写成 Linux、macOS 都已实测。业务层还应另外验证副作用与重试行为：超时说明本次等待没有按期完成，是否允许重试、结果能否查询、已写入的数据怎样对账，需要任务协议给出答案。

当日志再次出现 TimeoutExpired，先看使用的是哪个入口，再看谁负责结束和回收进程。用状态、后续动作与清理结果一起验证，才能让“超时之后发生了什么”成为可检查的事实。