假设脚本调用了一个命令,命令退出码是 7,外层的 try/except 却没有接到异常。另一条命令往 stderr 写了提示,退出码反而是 0。这里没有矛盾:subprocess.run() 默认不把非零退出转成异常,stderr 也不是成功与否的判定开关。
本文按 Python 3.14 文档解释行为,用 CPython 3.14.3 在 Linux 上运行完整实验。先把进程状态和输出分开,再看业务结果。
run() 会等待直接子进程结束。没有触发启动、通信等其他异常时,默认的 check=False 允许它在子进程非零退出后,返回 CompletedProcess。退出状态放在 returncode 里,调用参数放在 args 里。
只写 try/except subprocess.CalledProcessError,却没有设置 check=True,也没有随后检查 returncode,就漏掉了这条失败路径。try/except 不会替你开启退出码检查。
正常返回只能说明这次 Python 调用没有向外抛异常。检查应放在读取输出、更新任务状态等后续步骤之前:如果代码先写下成功记录,再去读 returncode,虽然最后发现了非零退出,先前的成功记录已经不准确。把检查时机放对,比单独加一层 try 更有用。
两种写法都合理。如果调用方需要按不同退出码继续分流,可以保留 check=False,读取 result.returncode;如果当前步骤要求退出码为 0,check=True 更直接。至于某个工具把 1 定义为“未找到匹配”还是“执行失败”,仍要看那个工具的约定。
POSIX 上的负 returncode 还可能表示子进程被信号终止,不能把所有非零值都翻译成某一种业务错误。
对于直接子进程的非零退出,check=False 返回 CompletedProcess,check=True 抛出 CalledProcessError。这是两条替代处理路径,不是先返回结果、再自动抛一次异常。

图:直接子进程非零退出时的两种处理方式(AI辅助示意)。stderr有无不决定退出状态,退出0不等于业务通过。
CalledProcessError 的 returncode 是退出状态,cmd 是调用参数。提前捕获了输出,异常对象才有对应的 stdout、stderr;output 是 stdout 的别名。排障时读取这些属性,比只保留一句“命令执行失败”更有用。
如果已经拿到结果,还可以调用 result.check_returncode():非零时抛出 CalledProcessError,0 时正常返回 None。它检查已有结果,不会重跑命令,也不会补抓之前没有捕获的输出。
stderr 常用于错误信息,也可能承载警告、进度或普通诊断。程序可以往 stderr 写字后退出 0,也可以什么都不写就退出 7。判断进程状态要读 returncode,而不是写 if result.stderr 就认定失败。
capture_output=True 只负责同时捕获 stdout 和 stderr,不会自动打开 check。反过来,check=True 也不会自动捕获输出。这两个参数解决的是不同问题。
未捕获时,结果中的 stdout、stderr 是 None;捕获后没有内容,在二进制模式下是 b'',在文本模式下是空字符串。None 表示没有这份捕获结果,不能解释成“子进程没写过任何东西”。
若使用 stdout=PIPE、stderr=STDOUT,两个通道合并进 stdout,stderr 属性仍为 None。这时也不能从 stderr 为 None 推断没有诊断输出。合并通道与 capture_output=True 不要同时设置。
输出文本里写着“失败”或“成功”,也不会让 subprocess 自动理解其含义。标准库只拿到状态与字节或文本,不认识每个工具的日志格式。若工具有结构化结果,优先按文档解析;若只能检查日志,应明确哪些文本表示什么,不能把关键词搜索当作所有命令通用的验收。
把下面代码保存成 code.py,用 Python 执行。run() 从 3.5 提供,capture_output 和 text 参数从 3.7 提供;本例的 API 用法要求 3.7 及以上,本次实跑版本是 3.14.3,不代表已经覆盖所有旧版本或操作系统。
实验只启动当前解释器的短小子程序,使用参数列表和 shell=False。临时工作目录会在退出上下文时清理;子进程使用空环境和隔离模式,不读取用户配置。这里是 Linux 教学实验的隔离约定,不是适用于任意程序的安全沙箱。
文本捕获显式指定 UTF-8,子解释器也开启 UTF-8;传给 -c 的源码只含 ASCII,中文通过转义构造。二进制对照则保留原始 bytes,避免把系统默认编码混入退出状态实验。
import json
import subprocess
import sys
import tempfile
from pathlib import Path
def require(condition, message):
if not condition:
raise RuntimeError(message)
def expect_error(kind, operation):
try:
operation()
except kind as error:
return error
raise RuntimeError("expected " + kind.__name__)
def main():
passed = []
def case(name, *conditions):
for condition in conditions:
require(condition, name)
passed.append(name)
print("PASS {:02d} {}".format(len(passed), name))
def command(source):
require(source.isascii(), "child source must be ASCII")
return [sys.executable, "-I", "-X", "utf8", "-c", source]
with tempfile.TemporaryDirectory(prefix="subprocess-check-") as work:
def run(source, **options):
return subprocess.run(
command(source), stdin=subprocess.DEVNULL, shell=False,
cwd=work, env={}, **options
)
text = {"capture_output": True, "text": True,
"encoding": "utf-8", "errors": "strict"}
failed = run("import sys; sys.exit(7)", **text)
case("default_check_false", isinstance(failed, subprocess.CompletedProcess),
failed.returncode == 7, failed.stdout == "", failed.stderr == "")
explicit = run("import sys; sys.exit(8)", check=False, **text)
case("explicit_check_false", explicit.returncode == 8, explicit.stderr == "")
warning = run("import sys; sys.stderr.write('notice\\n')",
check=True, **text)
case("zero_with_stderr", warning.returncode == 0,
warning.stdout == "", warning.stderr == "notice\n")
source = ("import sys; sys.stdout.write('out\\n'); "
"sys.stderr.write('err\\n'); sys.exit(9)")
error = expect_error(subprocess.CalledProcessError,
lambda: run(source, check=True, **text))
case("checked_error_text", error.returncode == 9,
error.cmd == command(source), error.stdout == "out\n",
error.output == error.stdout, error.stderr == "err\n")
raw_error = expect_error(subprocess.CalledProcessError,
lambda: run(source, check=True, capture_output=True))
case("checked_error_bytes", raw_error.returncode == 9,
raw_error.stdout == b"out\n", raw_error.stderr == b"err\n")
deferred = expect_error(subprocess.CalledProcessError,
failed.check_returncode)
case("deferred_check_failure", deferred.returncode == 7,
deferred.cmd == failed.args, deferred.stdout == "", deferred.stderr == "")
case("deferred_check_success", warning.check_returncode() is None)
uncaptured = run("pass")
case("uncaptured_result_none", uncaptured.returncode == 0,
uncaptured.stdout is None, uncaptured.stderr is None)
uncaptured_error = expect_error(
subprocess.CalledProcessError,
lambda: run("import sys; sys.exit(6)", check=True)
)
case("uncaptured_error_none", uncaptured_error.returncode == 6,
uncaptured_error.stdout is None, uncaptured_error.stderr is None)
chinese = "import sys; sys.stdout.write('\\u4e2d\\u6587\\n')"
binary = run(chinese, capture_output=True, check=True)
case("binary_utf8", type(binary.stdout) is bytes,
binary.stdout == "中文\n".encode("utf-8"), binary.stderr == b"")
decoded = run(chinese, check=True, **text)
case("text_utf8", type(decoded.stdout) is str,
decoded.stdout == "中文\n", decoded.stderr == "")
missing = str(Path(work) / "program-does-not-exist")
for checked in (False, True):
launch_error = expect_error(
FileNotFoundError,
lambda: subprocess.run(
[missing], check=checked, capture_output=True, shell=False,
stdin=subprocess.DEVNULL, cwd=work, env={}
)
)
case("missing_program_check_" + str(checked).lower(),
launch_error.filename == missing)
def business_ok(result):
value = json.loads(result.stdout)
return (result.returncode == 0 and type(value) is dict
and value.get("ok") is True)
business_false = run("print('{\"ok\": false}')", check=True, **text)
case("exit_zero_business_false", business_false.returncode == 0,
json.loads(business_false.stdout)["ok"] is False,
not business_ok(business_false))
business_true = run("print('{\"ok\": true}')", check=True, **text)
case("exit_zero_business_true", business_ok(business_true))
combined = run("import sys; sys.stderr.write('notice\\n')", check=True,
stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
text=True, encoding="utf-8", errors="strict")
case("combined_streams", combined.returncode == 0,
combined.stdout == "notice\n", combined.stderr is None)
require(len(passed) == 16, "unexpected case count")
print("RESULT cases=16 passed=16")
if __name__ == "__main__":
main()本次实际输出依次列出 PASS 01 到 PASS 16,最后一行是 RESULT cases=16 passed=16。代码用显式检查抛出 RuntimeError,不依赖可能被优化模式移除的 assert。
其中,第1、2项说明非零退出可以正常返回;第3项说明 stderr 有内容也可以退出0;第4至9项对照异常属性、延后检查和未捕获的 None;第10、11项检查 bytes/text;第12、13项检查启动失败;第14、15项对照业务真假值;第16项检查合并通道。
check=False 不是“所有错误都不抛异常”。本次 Linux 实验尝试直接执行临时目录内不存在的程序,无论 check 为 False 还是 True,都得到 FileNotFoundError。它属于 OSError,不是 CalledProcessError:这里连目标程序都没有成功启动。
不要为了省事用一个宽泛的 except Exception 把这些情况全改成成功返回。启动失败应检查程序路径、权限等条件;已启动程序的非零退出则结合该工具的退出码和输出处理。文档还列出了 WSL、QEMU 用户态模拟中部分 posix_spawn 路径的差异,不能把这次 Linux 结果写成所有环境的绝对保证。
设置 timeout 后,run() 等待超时会走 TimeoutExpired,而不是 CalledProcessError。文档说明会终止并等待直接子进程,再重新抛出超时异常;但部分平台的初始进程创建不能被这个超时立即中断,也不能据此保证清理全部后代进程。本例没有做超时、进程树或网络实验。
另外,捕获输出会把数据放进内存。本例输出很小;遇到大量或无上限输出,应另行设计输出落盘、读取和容量预算,不能照搬 capture_output=True 就长期运行。
代码特意让子程序输出 JSON 对象 {"ok": false},同时退出 0。check=True 没有抛异常,JSON 也能正常解析,但 business_ok() 仍返回 False。
这里采用的是一个明确的教学约定:退出码为 0、JSON 顶层为对象,而且 ok 必须是布尔 True,才算这份结果通过。真实工具的成功字段、允许状态和结果完整性要按其协议检查。
已观察到的现象 | 这一步能确定什么 | 还需要检查什么 |
|---|---|---|
返回结果且 returncode 非零 | 直接子进程以非零状态结束 | 该工具对退出码的定义与诊断输出 |
check=True 正常返回 | 本次退出码检查没有拒绝结果 | 输出是否完整、业务字段是否满足约定 |
stderr 为空 | 捕获的该通道没有内容 | 退出码以及其他结果,不能据此报成功 |
JSON 解析成功 | 输出符合可解析的JSON形式 | 字段类型、含义与本次任务的成功条件 |
表中的判断有各自范围。实验要求 ok is True,不会把字符串或其他真值直接当作布尔确认;接入不同工具时,应替换这份教学契约。能解析 JSON,不等于内容符合业务要求;这段人工 JSON 实验也不是某个真实 CLI 的业务验收。
实际接入时,先区分程序有没有启动,再处理退出状态,最后按工具协议校验结果。异常日志可能包含参数、路径或输出,记录前还要脱敏,别把访问令牌跟着 cmd 一起写出去。
原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。
如有侵权,请联系 cloudcommunity@tencent.com 删除。