Bash 函數的返回值與錯誤碼

在撰寫 Shell 腳本時，許多人直覺地認為函數（Function）應該像 Python 或 C++ 那樣透過 return 關鍵字傳回數值。然而，Bash 的函數機制有其獨特的設計哲學。理解「返回值（Return Value）」與「輸出（Output）」的差異，是撰寫健壯腳本的关键。本文將深入探討 Bash 函數的錯誤碼機制、標準輸出處理，以及如何正確實現多值返回。

函數的「返回值」：僅供狀態檢查

在 Bash 中，函數執行完畢後，會回傳一個 0 到 255 之間的整數，這被稱為退出狀態碼（Exit Status Code）。

0：代表成功。
非 0：代表失敗或特定錯誤狀態。

這個機制源自 Unix 哲學：函數主要用於改變環境或執行動作，而非計算數據。因此，return 指令僅能用於設定這個狀態碼，無法直接傳回字串或複雜數據結構。

#!/bin/bash

# 定義一個簡單的檢查函數
check_status() {
    local user_input="$1"

    if [ "$user_input" -gt 10 ] 2>/dev/null; then
        echo "數值大於 10"
        return 0  # 明確標記成功
    else
        echo "數值小於或等於 10，或輸入非數字"
        return 1  # 明確標記失敗
    fi
}

# 呼叫函數並檢查返回值
check_status 15
echo "最後的退出碼: $?" # 輸出 0

check_status 5
echo "最後的退出碼: $?" # 輸出 1

在上方範例中，我們使用 $? 變數來取得上一個指令（在此為函數呼叫）的返回值。這是 Bash 中判斷函數是否「成功」執行的標準方式。

傳回數據：利用標準輸出（stdout）

既然 return 只能傳回數字，那麼如何讓函數傳回字串或列表呢？答案是利用 標準輸出（Standard Output）。函數透過 echo 將結果輸出到 stdout，呼叫者則透過命令替換（Command Substitution）來擷取這些內容。

#!/bin/bash

# 函數透過 echo 輸出數據
get_user_info() {
    local username="$1"
    # 模擬查詢結果，使用特殊字元分隔
    echo "uid:1000|home:/home/${username}|shell:/bin/bash"
}

# 擷取函數輸出
result=$(get_user_info "alice")

# 解析輸出
IFS='|' read -r uid home shell <<< "$result"

echo "使用者: alice"
echo "UID: $uid"
echo "主目錄: $home"
echo "Shell: $shell"

這裡的關鍵技巧在於使用 $() 包裹函數呼叫，並透過 IFS（內部欄位分隔符）來分割輸出內容。這種方式允許函數傳回任意複雜的數據結構。

最佳實踐：同時處理狀態與數據

在實際開發中，我們往往需要同時知道「執行是否成功」以及「執行的結果是什麼」。最穩健的做法是結合兩者：函數透過 echo 輸出數據，並透過 return 設定狀態碼。

#!/bin/bash

# 健壯的函數設計範例
safe_divide() {
    local dividend="$1"
    local divisor="$2"

    # 檢查輸入是否為數字
    if ! [[ "$dividend" =~ ^[0-9]+$ ]] || ! [[ "$divisor" =~ ^[0-9]+$ ]]; then
        echo "ERROR: 輸入必須是整數" >&2  # 錯誤訊息導向 stderr
        return 1  # 返回失敗狀態
    fi

    # 檢查除數是否為零
    if [ "$divisor" -eq 0 ]; then
        echo "ERROR: 除數不能為零" >&2
        return 2  # 返回特定錯誤碼 2
    fi

    # 計算結果並輸出到 stdout
    echo $(( dividend / divisor ))
    return 0  # 返回成功狀態
}

# 使用範例
result=$(safe_divide 10 3)
status=$?

if [ $status -eq 0 ]; then
    echo "計算成功: $result"
elif [ $status -eq 1 ]; then
    echo "輸入錯誤！"
elif [ $status -eq 2 ]; then
    echo "數學錯誤！"
fi

注意我們將錯誤訊息導向 stderr（檔案描述符 2），這樣可以確保當我們使用管道或重定向標準輸出時，錯誤訊息不會混入正常的數據流中。

常見問題

為什麼 return 不能傳回字串？ Bash 函數的設計初衷是模擬系統呼叫，系統呼叫僅能傳回整數狀態碼。若要傳回字串，必須依賴標準輸出。這是 Bash 與其他腳本語言最大的差異之一，初學者常在此栽跟頭。
如何區分「函數執行成功」與「函數沒有輸出」？ 如果一個函數執行成功但沒有產生任何輸出，$? 仍為 0，但 $() 擷取到的內容為空字串。建議在函數內部定義明確的輸出格式（例如 JSON 或固定欄位），並在呼叫端檢查輸出內容是否為預期的格式，而非僅依賴 $?。

小結

掌握 Bash 函數的返回值與錯誤碼，核心在於理解「狀態碼用於控制流程，標準輸出用於傳遞數據」。透過結合 return 設定狀態、echo 傳遞數據，並將錯誤訊息導向 stderr，您可以撰寫出既專業又易於除錯的 Shell 腳本。在 Ubuntu 22.04 或 Debian 12 環境中，這些技巧同樣適用，能顯著提升自動化腳本的可靠性。