cURL 是 PHP 中功能最強大的 HTTP 客戶端庫,支援 HTTP/HTTPS、FTP、FTPS、SFTP、SCP、TELNET、LDAP、FILE 等多種協議,並完美處理 Cookie、Session、認證、代理、文件上傳、斷點續傳等複雜場景。相比之下,file_get_contents() 僅適合簡單 GET 請求,面對表單提交、Cookie 維持、HTTPS 驗證等場景無能為力。
php.iniextension=php_curl.dll(Windows)或 extension=curl.so(Linux/Mac);php -m | grep curl 或 phpinfo() 中出現 cURL support enabled$ch = curl_init(); 返回 cURL 句柄curl_setopt($ch, OPTION, VALUE); 可多次調用$output = curl_exec($ch); 返回響應體(或直接輸出)curl_close($ch); 釋放資源<?php
$ch = curl_init();
// 目標 URL
curl_setopt($ch, CURLOPT_URL, "https://www.baidu.com");
// 關鍵:返回響應體而非直接輸出(預設 CURLOPT_RETURNTRANSFER=0 直接輸出)
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
// 不需要響應標頭
curl_setopt($ch, CURLOPT_HEADER, 0);
// 執行
$html = curl_exec($ch);
// 錯誤處理
if ($html === false) {
echo 'cURL Error: ' . curl_error($ch);
} else {
echo $html;
}
curl_close($ch);
?>
| 選項常量 | 用途 | 典型值 |
|---|---|---|
CURLOPT_URL | 請求地址 | "https://api.example.com/users" |
CURLOPT_RETURNTRANSFER | 1=返回字串, 0=直接輸出 | 1 |
CURLOPT_HEADER | 1=包含響應標頭, 0=不包含 | 0 |
CURLOPT_POST | 1=啟用 POST | 1 |
CURLOPT_POSTFIELDS | POST 數據(陣列=multipart/form-data, 字串=application/x-www-form-urlencoded) | ['field'=>'value'] |
CURLOPT_HTTPHEADER | 自定義請求標頭陣列 | ['Authorization: Bearer xxx', 'Content-Type: application/json'] |
CURLOPT_TIMEOUT | 最大執行秒數(總超時) | 30 |
CURLOPT_CONNECTTIMEOUT | 連接階段超時秒數 | 10 |
CURLOPT_SSL_VERIFYPEER | 驗證 SSL 憑證(生產環境建議 1) | 1 (開發可設 0) |
CURLOPT_SSL_VERIFYHOST | 檢查 SSL 憑證 CN 與主機名匹配 | 2 |
CURLOPT_FOLLOWLOCATION | 1=自動跟隨 3xx 重定向 | 1 |
CURLOPT_MAXREDIRS | 最大重定向次數 | 5 |
CURLOPT_COOKIEJAR | Cookie 儲存文件路徑(持久化) | /tmp/cookies.txt |
CURLOPT_COOKIEFILE | 讀取 Cookie 文件 | /tmp/cookies.txt |
CURLOPT_USERAGENT | 自定義 User-Agent | 'Mozilla/5.0 (compatible; MyBot/1.0)' |
CURLOPT_PROXY | 代理伺服器 | '127.0.0.1:8080' |
CURLOPT_PROXYUSERPWD | 代理認證 "user:pwd" | 'user:pass' |
<?php
function postJson($url, $data, $timeout = 10) {
$ch = curl_init($url);
$options = [
CURLOPT_POST => 1,
CURLOPT_POSTFIELDS => json_encode($data),
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'Accept: application/json',
'User-Agent: MyApp/1.0'
],
CURLOPT_RETURNTRANSFER => 1,
CURLOPT_TIMEOUT => $timeout,
CURLOPT_CONNECTTIMEOUT => 5,
CURLOPT_SSL_VERIFYPEER => 1, // 生產環境必開
];
curl_setopt_array($ch, $options);
$response = curl_exec($ch);
$errno = curl_errno($ch);
$error = curl_error($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($errno) {
return ['success' => false, 'error' => $error, 'errno' => $errno];
}
return [
'success' => true,
'http_code' => $httpCode,
'body' => json_decode($response, true),
'raw' => $response
];
}
// 使用
$result = postJson('https://httpbin.org/post', ['name' => 'Alice', 'age' => 25]);
var_dump($result);
?>
<?php
$ch = curl_init('https://api.example.com/upload');
$filePath = '/path/to/local/file.jpg';
// PHP 5.5+ 推薦使用 CURLFile 類(安全、支援檔名/MIME)
$cfile = new CURLFile($filePath, 'image/jpeg', 'avatar.jpg');
$data = [
'file' => $cfile,
'user_id' => 123,
'token' => 'abcxyz'
];
curl_setopt_array($ch, [
CURLOPT_POST => 1,
CURLOPT_POSTFIELDS => $data,
CURLOPT_RETURNTRANSFER => 1,
CURLOPT_TIMEOUT => 30,
]);
$resp = curl_exec($ch);
curl_close($ch);
?>
舊版寫法(已棄用,不安全): '@'.$filePath.';filename=xxx.jpg;type=image/jpeg' 需開啟 CURLOPT_SAFE_UPLOAD = false,強烈不建議。
curl_error($ch):獲取最後一次錯誤描述curl_errno($ch):錯誤代碼(如 28=超時, 60=SSL 憑證驗證失敗, 7=連接失敗)curl_getinfo($ch):獲取詳細傳輸資訊(耗時、HTTP 碼、解析 IP 等)CURLOPT_SSL_VERIFYPEER => 0, CURLOPT_SSL_VERIFYHOST => 0cURL 是 PHP 後端開發「瑞士軍刀」。熟記 四步流程、掌握 高頻選項、善用 curl_setopt_array() 批量設置、務必做 錯誤處理與超時控制,即可應對 99% 的 HTTP 交互場景。下一步可探索 curl_multi 並發請求、斷點續傳、WebSocket 等進階用法。