Python subprocess 实战：把参数、退出码和超时分开处理
自动化脚本调用外部程序时，常把一串命令拼好就运行，再凭终端有没有文字判断成功。这样容易混淆参数解析、程序失败和执行超时。本文使用 Python 3.9 及以上标准库，通过当前解释器启动三个很小的子进程；全部文件位于临时目录，不依赖外部服务，也不会运行输入中的 shell 片段。
AI生成概念配图：独立参数进入受控进程，计时器限定等待范围。仅作概念说明，不代表实际界面或实测结果。
先固定解释器，再传递参数列表
把每个参数放在列表中的一个元素里，保留默认的 shell=False。一个参数里含空格、分号或星号时，仍按原样传给目标程序。不要为了“保险”再给列表元素套上 shell 引号，否则引号可能变成参数的一部分。这里用 sys.executable 避免误调用另一套 Python；工作目录也显式指定。
import json
import subprocess
import sys
from tempfile import TemporaryDirectory
with TemporaryDirectory(prefix="subprocess-demo-") as work:
payload = ["two words", "a;b", "*.txt"]
script = "import json,sys; print(json.dumps(sys.argv[1:]))"
result = subprocess.run(
[sys.executable, "-c", script, *payload],
cwd=work,
check=True,
capture_output=True,
text=True,
encoding="utf-8",
timeout=5,
)
assert json.loads(result.stdout) == payload
print("arguments:", json.loads(result.stdout))
try:
subprocess.run(
[sys.executable, "-c",
"import sys; print('bad input', file=sys.stderr); sys.exit(7)"],
cwd=work, check=True, capture_output=True,
text=True, encoding="utf-8", timeout=5,
)
except subprocess.CalledProcessError as exc:
print("failed:", exc.returncode, exc.stderr.strip())
try:
subprocess.run(
[sys.executable, "-c", "import time; time.sleep(2)"],
cwd=work, check=True, capture_output=True, timeout=0.1,
)
except subprocess.TimeoutExpired:
print("timed out")正常分支会完整拿回三个字符串；失败分支显示退出码七和标准错误中的 bad input；最后进入超时分支。这是三个独立判断，不应只搜索日志中有没有 error。真实工具对零退出码的定义仍由工具协议决定，有时还需解析结构化结果、检查产物存在并做内容验收。
还有一类错误发生在程序尚未启动时，例如可执行文件不存在或没有执行权限。这通常表现为操作系统异常，应与已启动后返回非零分开记录。更换工作目录也会改变目标程序读取相对路径的含义；配置文件与输出目录最好先解析成明确路径，避免依赖调用者碰巧所在的位置。
错误输出和进程失败不是同一个概念
check=True 把非零退出转换成 CalledProcessError，便于调用方按失败处理。标准错误流可能装的是警告或进度信息，标准输出也可能包含失败说明，所以两条流应分别保留。处理异常时记录退出码、必要诊断和调用位置即可；参数或输出若含令牌、文件内容等私密数据，应先做脱敏。
text=True 让输出按文本处理，encoding 明确解码方式；若外部程序输出原始字节或未知编码，应先保持二进制，再按协议解码。TimeoutExpired 的已捕获输出在相关属性中可能仍是 bytes，即使调用开启了文本模式，也不要直接按字符串拼接。正常结果和异常结果的字段类型应分别检查。
超时不是完整的资源管理方案
run 超时后会终止并等待它启动的直接子进程，随后抛出异常；一些平台的进程创建阶段无法立即中断，因此超时时间不是严格的端到端上限。目标程序若又创建了孙进程，不能据此保证整棵进程树都被回收。本文的子进程没有派生任务，复杂服务需另外设计进程组与关闭策略。
capture_output 会把收集到的内容留在内存。对持续运行的命令或巨量输出，应把流接到受控文件，或使用 Popen 实现有上限的读取与超时管理。不要一边等待程序退出，一边让它的输出管道没人读取。退出码处理正确，也不能挽救被无限日志耗尽的内存。
最后核对目标程序自己的参数协议
参数列表避免了一层 shell 解析，却不能自动消除目标程序的选项注入。例如用户输入以短横线开头时，工具仍可能把它解释成选项，应使用目标支持的参数结束标记或严格校验。Windows 批处理文件还有额外的 shell 行为，本文不把它当作普通可执行程序演示。需要管道、通配或重定向时，优先使用 Python 对应接口，并给每个外部步骤单独建立验证标准。
