PHP cURL 入門到精通：常見用法完整實戰指南

為什麼選擇 cURL？

雖然 file_get_contents()、file()、readfile() 可簡單抓取網頁，但它們無法處理：POST 請求、檔案上傳、Cookie 管理、HTTP 認證、代理伺服器、超時控制、錯誤處理、自訂 Header 等進階需求。cURL 是解決這些問題的標準工具。

四步基本流程

$ch = curl_init();                                    // 1. 初始化
curl_setopt($ch, CURLOPT_URL, 'https://api.example.com'); // 2. 設定選項
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);                           // 3. 執行並取得回應
curl_close($ch);                                      // 4. 關閉釋放

錯誤處理正確寫法

$response = curl_exec($ch);
if ($response === false) {  // 必須用 ===，因為空字串也是合法回應
    throw new Exception('cURL 錯誤: ' . curl_error($ch), curl_errno($ch));
}

// 取得詳細傳輸資訊
$info = curl_getinfo($ch);
echo "HTTP 狀態碼: {$info['http_code']}\n";
echo "總耗時: {$info['total_time']} 秒\n";
echo "下載大小: {$info['size_download']} bytes\n";

常見實戰場景

1. 發送 POST 請求（表單資料）

$post_data = [
    'username' => 'alice',
    'password' => 'secret',
    'action'   => 'login',
];

$ch = curl_init('https://example.com/login');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $post_data,  // 自動編碼為 application/x-www-form-urlencoded
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_COOKIEJAR      => 'cookies.txt', // 儲存 Cookie
    CURLOPT_COOKIEFILE     => 'cookies.txt', // 讀取 Cookie
]);
$response = curl_exec($ch);

2. 檔案上傳

$post_data = [
    'file' => new CURLFile('/path/to/photo.jpg', 'image/jpeg', 'photo.jpg'), // PHP 5.5+
    // 舊版寫法：'file' => '@/path/to/photo.jpg;type=image/jpeg;filename=photo.jpg'
    'description' => '個人大頭照',
];
curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data);

3. 檔案下載（大檔案邊下載邊寫入）

$url = 'https://example.com/large.zip';
$local_path = '/data/downloads/large.zip';

$fp = fopen($local_path, 'wb');
$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_FILE    => $fp,        // 直接寫入檔案指標
    CURLOPT_FOLLOWLOCATION => true,
]);
curl_exec($ch);
curl_close($ch);
fclose($fp);

4. HTTP Basic 認證

curl_setopt($ch, CURLOPT_USERPWD, 'username:password');
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);

5. 透過代理伺服器請求

curl_setopt($ch, CURLOPT_PROXY, '222.73.173.50:8080');
curl_setopt($ch, CURLOPT_PROXYUSERPWD, 'proxy_user:proxy_pass'); // 若需認證
curl_setopt($ch, CURLOPT_PROXYTYPE, CURLPROXY_HTTP); // 或 SOCKS5

6. 發送 JSON 資料（API 串接常用）

$payload = json_encode([
    'order_id' => '20240101001',
    'amount'   => 1234.56,
    'items'    => [['sku' => 'A001', 'qty' => 2]],
]);

$ch = curl_init('https://api.payment.com/orders');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS    => $payload,
    CURLOPT_HTTPHEADER    => [
        'Content-Type: application/json',
        'Content-Length: ' . strlen($payload),
        'Authorization: Bearer ' . $access_token,
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);

實用選項速查表

最佳實務建議

• 永遠啟用 CURLOPT_RETURNTRANSFER 以程式化處理回應
• 使用 curl_setopt_array() 批次設定選項，程式碼更清晰
• 生產環境務必驗證 SSL 憑證，勿關閉 CURLOPT_SSL_VERIFYPEER
• 建立可重用的 cURL 封裝類別（如文章中的 httpClient）
• 記錄完整的請求/回應 Log 便於除錯
• 設定合理的超時值，避免阻塞進程