Python 中的 subprocess.check_output

subprocess.check_output() 會以你提供的引數執行程式，並回傳其標準輸出。將引數以清單形式傳入，即可在不建構 shell 命令字串的情況下擷取命令的結果。

在 Python 中使用 subprocess.check_output()

當你的腳本需要命令的輸出，且應將非零結束狀態視為失敗時，請使用 subprocess.check_output()。此函式是 Python subprocess 模組的一部分；它不會並行執行命令。

語法與回傳行為

簡略的呼叫形式為 subprocess.check_output(args, *, cwd=..., timeout=..., text=None, ...)；這並非完整的函式簽章。args 提供命令及其引數。cwd、timeout 與 text 為關鍵字引數：cwd 選擇子程序的工作目錄，timeout 限制呼叫等待的時間，text 控制擷取的輸出是否解碼為文字。text 的預設值為 None，因此除非啟用文字模式，否則輸出為位元組。完整的 API 參考請參閱 Python subprocess 文件。

預設情況下，回傳值為位元組。當你需要 Python 字串時，請將其解碼。使用 text=True 時，Python 會替你解碼擷取的輸出。這個精簡範例讓 Python 直譯器輸出固定的一行，擷取其位元組，將其以 UTF-8 解碼，並把該行寫入標準輸出。

import subprocess
import sys

output = subprocess.check_output(
    [sys.executable, "-c", "print('ready')"]
)
print(output.decode("utf-8"), end="")

ready

引數清單使可執行檔與其引數保持分離。例如 subprocess.check_output(["git", "status"]) 這樣的呼叫會擷取目前目錄中 Git 的標準輸出。

使用 subprocess.check_output() 執行 Git 命令

請在你想要檢查的儲存庫中執行這些呼叫。若要讀取目前分支，請使用 subprocess.check_output(["git", "rev-parse", "--abbrev-ref", "HEAD"], text=True).strip()。當儲存庫處於分離 HEAD（detached HEAD）狀態時，Git 會回報 HEAD，而非分支名稱。

若要列出已設定的遠端及其 URL，請使用 subprocess.check_output(["git", "remote", "-v"], text=True)。若要檢視已暫存、未暫存與未追蹤的變更，請使用 subprocess.check_output(["git", "status"], text=True)。這些命令取決於 Git 已安裝，且目前工作目錄位於目標儲存庫內；需要時，請將 cwd 設定為該儲存庫路徑。

處理錯誤並在 check_output() 與 run() 之間選擇

如果子程序以非零狀態結束，subprocess.check_output() 會引發 CalledProcessError。其 returncode 記錄結束狀態，其 output 屬性包含擷取到的標準輸出。標準錯誤預設不會被擷取；如果你想將它與標準輸出合併，請傳入 stderr=subprocess.STDOUT。

引數清單不需要 shell。避免透過 shell=True 將不受信任的輸入傳給命令，因為 shell 的解譯可能允許命令注入；僅靠 shell 引號並不是通用的安全修復方法。

對於擷取輸出並將失敗的結束視為錯誤這項專注的任務，請選擇 subprocess.check_output()。當你還需要 CompletedProcess、對標準串流有更多控制，或需要選擇如何處理結束狀態時，請選擇 subprocess.run()。例如，subprocess.run(args, capture_output=True, text=True, check=False) 會回傳狀態與擷取到的串流，供你的程式碼檢查。