Python subprocess.run 怎样让非零退出码变成异常

如果你希望外部命令返回非零退出码时直接进入 except，关键参数就是 check=True。subprocess.run() 默认使用 check=False，命令即使失败也会返回 CompletedProcess；改成 check=True 后，非零退出码会抛出 subprocess.CalledProcessError。

下面这条边界要先记住：进程已经启动但返回失败，是 CalledProcessError；程序根本没有启动成功，例如可执行文件不存在，则通常是 FileNotFoundError 这类 OSError。两者的处理位置不同。

默认写法为什么不会抛异常

run() 等待子进程结束后返回一个 CompletedProcess 对象。它的 returncode 通常为 0 表示成功，非零值表示子进程报告了失败，但 Python 不会因为这个值自动抛异常。

import subprocess

# 默认 check=False：命令失败仍返回对象，调用方必须主动检查 returncode。
result = subprocess.run(
    ["python", "-c", "print('child failed'); raise SystemExit(3)"],
    capture_output=True,
    text=True,
)

# 这里用明确分支把退出码转换成业务日志，而不是假设调用已经成功。
if result.returncode != 0:
    print("命令失败：", result.returncode)
    print("错误输出：", result.stderr)

这种写法适合“失败也是正常分支”的场景，例如探测某个命令是否存在。但如果失败必须中断当前流程，手动检查很容易被遗漏，这正是 check=True 的价值。

用 check=True 把非零退出码变成异常

给 subprocess.run() 传入 check=True 后，只要子进程返回非零退出码，Python 就抛出 CalledProcessError。正常退出码为 0 时，函数仍然返回 CompletedProcess。

import subprocess

try:
    # check=True 把非零退出码提升为 CalledProcessError。
    completed = subprocess.run(
        ["python", "-c", "raise SystemExit(7)"],
        check=True,
    )
except subprocess.CalledProcessError as exc:
    # 异常中保留命令参数和退出码，便于统一记录或转换成业务异常。
    print("命令：", exc.cmd)
    print("退出码：", exc.returncode)

注意，check=True 只关心退出状态，不会自动把标准输出和标准错误保存下来。如果排障需要查看错误文本，还要配合 capture_output=True 或显式设置 stdout=subprocess.PIPE、stderr=subprocess.PIPE。

让 CalledProcessError 带上可读的错误输出

实际项目里通常同时使用 check=True、capture_output=True 和 text=True。这样异常的 stdout、stderr 会是字符串，日志不需要再手动解码字节。

import subprocess

try:
    # text=True 让捕获的标准流按文本处理，避免异常日志直接出现 bytes。
    subprocess.run(
        ["python", "-c", "import sys; print('out'); print('err', file=sys.stderr); raise SystemExit(2)"],
        check=True,
        capture_output=True,
        text=True,
    )
except subprocess.CalledProcessError as exc:
    # stdout/stderr 只有在捕获后才有内容；生产日志仍应注意脱敏。
    detail = (exc.stderr or exc.stdout or "无错误输出").strip()
    print(f"外部命令失败，code={exc.returncode}，detail={detail}")

如果需要把标准错误和标准输出合并，可以用 stderr=subprocess.STDOUT，但此时读取的是 stdout，stderr 会是 None。不要同时传 capture_output=True 和 stdout/stderr，这两种配置互斥。

区分命令失败和启动失败

CalledProcessError 的前提是子进程已经被启动并返回了非零状态。如果命令名拼写错误、路径不存在或权限导致进程无法启动，通常会在创建进程阶段抛出 OSError，最常见的具体类型是 FileNotFoundError。

import subprocess

try:
    # 这里的命令名不存在时，通常不会产生退出码，而是直接启动失败。
    subprocess.run(["command-that-does-not-exist"], check=True)
except FileNotFoundError as exc:
    # 启动失败没有可供读取的 CalledProcessError.returncode。
    print("找不到可执行文件：", exc.filename)
except subprocess.CalledProcessError as exc:
    # 只有程序成功启动并返回非零码时才会进入这里。
    print("程序返回失败：", exc.returncode)

因此不要只捕获 CalledProcessError 就认为所有子进程问题都被覆盖了。对固定工具链可以先用绝对路径，或用 shutil.which() 检查 PATH 中的可执行文件，再决定是否启动。

把检查逻辑收口成可复用函数

当多个业务入口都要执行外部命令时，可以在一处统一设置 check=True、文本输出和超时，并把底层异常转换成项目自己的错误类型。这样调用方不需要重复记住每个参数的组合。

from collections.abc import Sequence
import subprocess


def run_checked(args: Sequence[str]) -> str:
    """执行命令；成功返回标准输出，失败保留原始异常上下文。"""
    try:
        # timeout 防止子进程无限等待，check 负责统一提升非零退出码。
        result = subprocess.run(
            list(args),
            check=True,
            capture_output=True,
            text=True,
            timeout=30,
        )
        return result.stdout
    except subprocess.CalledProcessError as exc:
        # 使用 from None 只隐藏实现细节时才这样做；这里保留异常链便于定位。
        raise RuntimeError(f"命令返回 {exc.returncode}: {exc.stderr}") from exc
    except OSError as exc:
        # 启动失败与命令返回失败分开转译，调用方可给出不同提示。
        raise RuntimeError(f"命令无法启动: {exc}") from exc


# 传入参数列表，避免把用户输入拼成 shell 命令字符串。
output = run_checked(["python", "-c", "print('ok')"])
print(output.strip())

这里把参数作为列表传入，默认不启用 shell；这能减少 quoting 和路径空格带来的歧义。若业务确实需要 shell 特性，应单独评估输入来源和安全边界，而不是为了让 check=True 生效而打开 shell=True。

常见误区与最小决策表

小结

subprocess.run() 把非零退出码变成异常只需要 check=True。需要诊断文本时再加 capture_output=True 与 text=True；需要覆盖“程序没有启动”的情况，则要同时处理 OSError。把这些选项集中在一个小封装里，通常比在每个调用点手写 returncode 判断更不容易漏检。

相关问题

check=True 会捕获标准错误吗？

不会。它只负责根据非零退出码抛出 CalledProcessError；标准错误是否可读取，取决于是否配置了输出捕获或重定向。

CalledProcessError 的退出码在哪里？

在异常对象的 returncode 属性中；执行命令和参数在 cmd 中，捕获到的标准输出和错误输出分别可从 stdout、stderr 读取。

为什么找不到命令时没有 CalledProcessError？

因为进程还没有成功启动，没有产生子进程退出码。此时应按启动错误处理 FileNotFoundError 或其他 OSError。