PHP cURL 初始化與執行完整參數指南（入門到進階）

基本初始化流程

<?php
$ch = curl_init(); // 初始化 cURL 會話

// 設定基本選項
curl_setopt_array($ch, [
    CURLOPT_URL => 'https://api.example.com/endpoint', // 目標 URL
    CURLOPT_RETURNTRANSFER => true,                    // 回傳字串而非直接輸出
    CURLOPT_HEADER => false,                           // 不包含回應 Header
    CURLOPT_FOLLOWLOCATION => true,                    // 自動跟隨重導向
    CURLOPT_MAXREDIRS => 10,                           // 最大重導向次數
    CURLOPT_TIMEOUT => 30,                             // 總超時秒數
    CURLOPT_CONNECTTIMEOUT => 10,                      // 連線超時秒數
    CURLOPT_SSL_VERIFYPEER => true,                    // 驗證 SSL 憑證 (生產必開)
    CURLOPT_SSL_VERIFYHOST => 2,                       // 驗證 hostname
    CURLOPT_USERAGENT => 'MyApp/1.0 (+https://example.com)', // 使用者代理
]);

// 執行請求
$response = curl_exec($ch);

// 錯誤檢查
if ($response === false) {
    $errno = curl_errno($ch);
    $error = curl_error($ch);
    throw new RuntimeException("cURL 錯誤 [$errno]: $error");
}

// 取得傳輸資訊
$info = curl_getinfo($ch);
$httpCode = $info['http_code'];
$totalTime = $info['total_time'];

// 關閉會話
curl_close($ch);

// 處理回應
$data = json_decode($response, true);
?>

常用選項分類速查表

POST 請求完整範例

<?php
function postJson($url, array $data, array $headers = []) {
    $ch = curl_init($url);
    $jsonData = json_encode($data);
    
    $defaultHeaders = [
        'Content-Type: application/json',
        'Accept: application/json',
        'Content-Length: ' . strlen($jsonData),
    ];
    
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => $jsonData,
        CURLOPT_HTTPHEADER => array_merge($defaultHeaders, $headers),
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 30,
        CURLOPT_SSL_VERIFYPEER => true,
    ]);
    
    return curl_exec($ch);
}

// 表單檔案上傳 (multipart/form-data)
function postFile($url, string $filePath, string $fieldName = 'file', array $extraFields = []) {
    $ch = curl_init($url);
    
    $postFields = $extraFields;
    // PHP 5.5+ 使用 CURLFile
    $postFields[$fieldName] = new CURLFile($filePath, mime_content_type($filePath), basename($filePath));
    
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => $postFields,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 60,
    ]);
    
    return curl_exec($ch);
}
?>

並發請求：curl_multi 批次處理

<?php
function multiRequest(array $urls, array $options = []) {
    $mh = curl_multi_init();
    $handles = [];
    
    foreach ($urls as $i => $url) {
        $ch = curl_init($url);
        curl_setopt_array($ch, array_merge([
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_TIMEOUT => 30,
            CURLOPT_SSL_VERIFYPEER => true,
            CURLOPT_PRIVATE => $i, // 標識索引
        ], $options));
        
        curl_multi_add_handle($mh, $ch);
        $handles[$i] = $ch;
    }
    
    $running = null;
    do {
        curl_multi_exec($mh, $running);
        curl_multi_select($mh, 0.1); // 等待活動
    } while ($running > 0);
    
    $results = [];
    foreach ($handles as $i => $ch) {
        $error = curl_error($ch);
        $results[$i] = [
            'content' => $error ? null : curl_multi_getcontent($ch),
            'error' => $error,
            'info' => curl_getinfo($ch),
        ];
        curl_multi_remove_handle($mh, $ch);
        curl_close($ch);
    }
    
    curl_multi_close($mh);
    return $results;
}

// 使用：同時請求 10 個 API
$urls = array_map(fn($i) => "https://api.example.com/item/$i", range(1, 10));
$responses = multiRequest($urls);
?>

最佳實務清單

1. ✅ 生產環境 永遠啟用 SSL 驗證 (CURLOPT_SSL_VERIFYPEER => true)
2. ✅ 設定合理 超時時間 避免阻塞進程
3. ✅ 使用 CURLOPT_RETURNTRANSFER 取得回應字串
4. ✅ 檢查 curl_errno() 而非只判斷 curl_exec() === false
5. ✅ 使用 curl_getinfo() 取得 HTTP 狀態碼、耗時等資訊
6. ✅ 大檔案下載使用 CURLOPT_WRITEFUNCTION 串流寫入檔案
7. ✅ 重複請求同一域名時重用 handle (保持連線池)
8. ✅ 記錄請求/回應日誌 (除敏感欄位) 便於除錯
9. ✅ 現代專案建議使用 Guzzle 或 Symfony HttpClient 封裝