subprocess 文本输出怎么配置或排查

用 subprocess 调外部程序时，文本输出问题通常不是命令本身坏了，而是“字节流、编码和输出通道”没有分开处理。最稳妥的写法是：需要字符串就显式设置 text=True 和 encoding，同时捕获 stdout、stderr，再用 returncode 判断结果。

不要只把 universal_newlines=True 当成乱码修复开关。先确认子进程输出的实际编码，再决定使用 encoding='utf-8'、errors='replace'，还是保留 bytes 自己解码。

先分清二进制输出和文本输出

subprocess.run() 默认不会替你猜编码。即使命令打印的是中文，capture_output=True 得到的 result.stdout 仍可能是 bytes。只有启用文本模式，或者直接指定编码，返回值才会变成 str。

import subprocess

# 这里明确要求 stdout/stderr 按 UTF-8 解码成字符串，便于后续查找文本。
result = subprocess.run(
    ["python", "-c", "print('任务完成')"],
    capture_output=True,
    text=True,
    encoding="utf-8",
    errors="strict",
)

# 返回码与两条文本流分开读取，不把 stderr 当成 stdout 的替代品。
print(result.returncode)
print(result.stdout.strip())
print(result.stderr.strip())

这里的关键不是 text=True 这个名字，而是它把标准流包成文本流；encoding 决定如何解码，errors 决定遇到非法字节时怎么处理。若你需要保留原始字节，删掉这三个参数，改为拿到 bytes 后在业务边界统一调用 decode()。

编码、错误处理和两条输出流要一起设计

“没有输出”不一定是命令没有工作。很多命令把提示、警告和错误写到 stderr，而把结果写到 stdout。只读取前者或后者，都会造成误判。若希望统一查看两条流，可以让 stderr 指向 STDOUT；若要区分信息来源，就分别捕获。

import subprocess

# 分开保存正常输出和错误输出，错误时仍能看到完整上下文。
try:
    result = subprocess.run(
        ["python", "-c", "import sys; print('结果'); print('提示', file=sys.stderr)"],
        stdout=subprocess.PIPE,
        stderr=subprocess.PIPE,
        text=True,
        encoding="utf-8",
        errors="replace",  # 外部程序混入非法字节时保留可读线索
        check=True,
        timeout=10,
    )
except subprocess.CalledProcessError as exc:
    # check=True 失败时，异常对象仍可能携带 stdout、stderr 和 returncode。
    print(f"命令失败: {exc.returncode}")
    print(exc.stdout or "")
    print(exc.stderr or "")
except subprocess.TimeoutExpired as exc:
    # 超时属于生命周期问题，不要把它当成普通的空字符串。
    print(f"命令超时: {exc.timeout} 秒")

乱码、空输出和超时怎么排查

第一步看类型：type(result.stdout) 能快速判断是否已经进入文本模式。第二步看编码：命令行工具的编码可能受系统、环境变量或自身参数影响，父进程写 utf-8 并不代表子进程真的用 UTF-8。第三步看通道和状态：同时打印 stdout、stderr 和 returncode，再决定修编码还是修命令参数。

如果使用 Popen 持续读取，不要分别对 stdout.read() 和 stderr.read() 做无限等待；两个管道都可能被写满。更安全的收尾方式是 communicate()，并把 timeout、子进程终止和残留输出纳入异常处理。

常见问题

text=True 和 universal_newlines=True 有什么区别？

在 subprocess API 中，universal_newlines 是旧名称，text=True 更直观。两者都表示按文本模式打开标准流，但乱码是否解决仍取决于实际编码和参数。

什么时候应该保留 bytes？

需要处理协议数据、混合编码或精确保留原始字节时保留 bytes 更稳。把解码推迟到明确的业务边界，通常比让默认编码参与更容易排查。

capture_output=True 能和 stdout 一起使用吗？

不能同时再指定 stdout 或 stderr。要分别设置通道时使用 stdout=PIPE、stderr=PIPE；要合并两条流时使用 stderr=STDOUT。