您现在的位置：程式碼之家 >> 編程語言 > >> 網頁程式設計 >> PHP 程式設計 >> PHP 綜合知識

PHP cURL 入門教學：從安裝到核心四步流程完整掌握

編輯：PHP 綜合知識

環境安裝與驗證

# Ubuntu/Debian
apt update && apt install php-curl php8.2-curl

# CentOS/RHEL
yum install php-curl

# 驗證
php -m | grep curl
# 輸出 curl 表示成功

# php.ini 確認啟用
extension=curl

核心四步流程詳解

步驟 1：初始化 curl_init()

$ch = curl_init();  // 返回 resource 型別（PHP 8.0+ 為 CurlHandle 物件）

// 也可直接帶入 URL
$ch = curl_init('https://api.example.com');

返回的控制代碼後續所有操作都需要用到，必須保存變數。

步驟 2：設定選項 curl_setopt()

// 單一設定
curl_setopt($ch, CURLOPT_URL, 'https://api.example.com');

// 批次設定（推薦）
curl_setopt_array($ch, [
    CURLOPT_URL => 'https://api.example.com',
    CURLOPT_RETURNTRANSFER => true,  // 關鍵！否則直接輸出到瀏覽器
    CURLOPT_TIMEOUT => 10,
]);

步驟 3：執行 curl_exec()

$response = curl_exec($ch);  // 成功返回回應內容，失敗返回 false

if ($response === false) {
    echo "錯誤: " . curl_error($ch);
}

步驟 4：關閉 curl_close()

curl_close($ch);  // 釋放資源，釋放連線

最小可行範例

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://httpbin.org/get');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

echo $response;  // 輸出 JSON 回應

常見選項分類速記

類別	代表選項
目標控制	CURLOPT_URL, CURLOPT_CUSTOMREQUEST(GET/POST/PUT/DELETE)
輸出控制	CURLOPT_RETURNTRANSFER, CURLOPT_FILE(寫入檔案), CURLOPT_WRITEFUNCTION(回調)
輸入資料	CURLOPT_POST, CURLOPT_POSTFIELDS, CURLOPT_HTTPHEADER
SSL/安全	CURLOPT_SSL_VERIFYPEER, CURLOPT_SSL_VERIFYHOST, CURLOPT_CAINFO
連線行為	CURLOPT_TIMEOUT, CURLOPT_CONNECTTIMEOUT, CURLOPT_FOLLOWLOCATION, CURLOPT_MAXREDIRS
Cookie/Session	CURLOPT_COOKIE, CURLOPT_COOKIEJAR, CURLOPT_COOKIEFILE
代理/網路	CURLOPT_PROXY, CURLOPT_PROXYPORT, CURLOPT_PROXYTYPE, CURLOPT_INTERFACE
資訊獲取	curl_getinfo($ch, CURLINFO_HTTP_CODE / TOTAL_TIME / PRIMARY_IP / ...)

進階：封裝成可複用函式

function curlRequest(string $url, array $options = []): array {
    $defaults = [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 15,
        CURLOPT_CONNECTTIMEOUT => 10,
        CURLOPT_SSL_VERIFYPEER => true,  // 生產環境建議 true
        CURLOPT_FOLLOWLOCATION => true,
        CURLOPT_MAXREDIRS => 3,
        CURLOPT_USERAGENT => 'Mozilla/5.0 (compatible; PHP-cURL)',
    ];
    
    $ch = curl_init($url);
    curl_setopt_array($ch, array_merge($defaults, $options));
    
    $body = curl_exec($ch);
    $errno = curl_errno($ch);
    $error = curl_error($ch);
    $info = curl_getinfo($ch);
    curl_close($ch);
    
    return [
        'success' => $errno === 0,
        'body' => $body,
        'http_code' => $info['http_code'] ?? 0,
        'error_no' => $errno,
        'error_msg' => $error,
        'total_time' => $info['total_time'] ?? 0,
    ];
}

// 使用範例
$result = curlRequest('https://httpbin.org/post', [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode(['key' => 'value']),
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
]);

避坑指南

忘記 CURLOPT_RETURNTRANSFER：導致直接輸出，無法變數接收
POST 欄位格式錯誤：陣列 = multipart/form-data，字串 = application/x-www-form-urlencoded，JSON 需手動 json_encode + 設定 Header
SSL 驗證失敗：開發環境暫時關閉，生產必須開啟並配置 CA 憑證
超時未設定：預設無超時，掛起進程導致 FPM 耗盡
未關閉 handle：長時間運行腳本會洩漏檔案描述符

除錯技巧

// 開啟詳細輸出（僅除錯用）
curl_setopt($ch, CURLOPT_VERBOSE, true);
$verbose = fopen('php://temp', 'rw+');
curl_setopt($ch, CURLOPT_STDERR, $verbose);

// 執行後
rewind($verbose);
echo stream_get_contents($verbose);  // 顯示完整握手過程

總結

cURL 看似選項繁多，但核心只有「初始化→設定→執行→關閉」四步。建議先掌握 CURLOPT_URL、CURLOPT_RETURNTRANSFER、CURLOPT_POSTFIELDS、CURLOPT_HTTPHEADER 四大核心選項，再按需擴展。封裝通用函式可大幅減少樣板代碼，提升維護性。