curl_setopt 參數分類總覽
curl_setopt(CurlHandle $ch, int $option, mixed $value): bool 選項按值類型分為長整數、字符串、流資源、陣列/對象（部分）。以下為高頻選項分類速查表（PHP 8.2 / libcurl 7.88+）。
1. 行為控制 (長整數)
| 常量 | 說明 | 典型值/備註 |
|---|
CURLOPT_RETURNTRANSFER | 返回字符串而非直接輸出 | 必開 true，否則直接 echo |
CURLOPT_HEADER | 包含響應頭在輸出中 | true 便於調試/解析 Set-Cookie |
CURLOPT_FOLLOWLOCATION | 自動跟隨 3xx 重定向 | true，配合 CURLOPT_MAXREDIRS (默認 20) |
CURLOPT_FAILONERROR | HTTP ≥ 400 視為失敗 | true 觸發 CURLE_HTTP_RETURNED_ERROR |
CURLOPT_SSL_VERIFYPEER | 驗證服務器 SSL 證書 | 生產必開 true，測試可 false |
CURLOPT_SSL_VERIFYHOST | 驗證證書 CN/SAN 匹配主機名 | 2 (默認嚴格)，0 不驗證，1 已棄用 |
CURLOPT_TIMEOUT | 最大執行秒數 | 整數秒，含連接+傳輸 |
CURLOPT_CONNECTTIMEOUT | 連接階段超時秒數 | 建議 5-10s，防止掛起 |
CURLOPT_LOW_SPEED_LIMIT/CURLOPT_LOW_SPEED_TIME | 低速限制觸發中斷 | 如 1024, 30 表示 30s 內平均 <1KB/s 則斷開 |
CURLOPT_BUFFERSIZE | 讀寫緩衝區大小 | 默認 16KB，大文件可調大 |
CURLOPT_HTTP_VERSION | 指定 HTTP 版本 | CURL_HTTP_VERSION_2_0、CURL_HTTP_VERSION_1_1 |
CURLOPT_PIPEWAIT | 等待管道/多路複用 | HTTP/2 多路複用優化 |
2. 請求構造 (字符串/陣列)
| 常量 | 說明 | 典型用法 |
|---|
CURLOPT_URL | 請求地址 | 必填，含 query string |
CURLOPT_CUSTOMREQUEST | 自定義 HTTP 方法 | 'GET'/'POST'/'PUT'/'DELETE'/'PATCH' |
CURLOPT_POST | 發送 POST 請求 | true 隱含 CURLOPT_POSTFIELDS |
CURLOPT_POSTFIELDS | POST 數據 | 陣列 => multipart/form-data；字符串 => application/x-www-form-urlencoded |
CURLOPT_HTTPHEADER | 自定義請求頭 | ['Content-Type: application/json', 'Authorization: Bearer ...'] |
CURLOPT_USERAGENT | User-Agent | 模擬瀏覽器或標識服務名 |
CURLOPT_REFERER | Referer 頭 | 防盜鏈、統計追蹤 |
CURLOPT_COOKIE | 直接發送 Cookie 字符串 | 'name=value; name2=value2' |
CURLOPT_COOKIEFILE/CURLOPT_COOKIEJAR | Cookie 文件讀/寫 | 同一文件實現會話保持 |
CURLOPT_USERNAME/CURLOPT_PASSWORD | HTTP Basic Auth | 替代 URL 中嵌入憑證 |
CURLOPT_PROXY/CURLOPT_PROXYPORT | 代理服務器 | 'https://proxy:3128'、CURLOPT_PROXYTYPE |
CURLOPT_PROXYUSERPWD | 代理認證 | 'user:pass' |
3. 流與回調 (資源/可調用)
| 常量 | 說明 | 回調簽名 |
|---|
CURLOPT_FILE (CURLOPT_INFILE) | 響應體寫入文件句柄 | fopen('out.bin','wb')，大文件直寫磁盤 |
CURLOPT_WRITEFUNCTION | 響應體寫入回調 | function($ch, $data): int { return strlen($data); } 返回寫入字節數 |
CURLOPT_READFUNCTION | 請求體讀取回調 (上傳) | function($ch, $fd, $max): string |
CURLOPT_HEADERFUNCTION | 響應頭解析回調 | function($ch, $header): int |
CURLOPT_PROGRESSFUNCTION | 進度回調 | 需 CURLOPT_NOPROGRESS=false，function($ch, $dlTotal, $dlNow, $ulTotal, $ulNow): int |
CURLOPT_DEBUG_FUNCTION | 調試信息回調 | function($ch, $type, $data): int，需 CURLOPT_VERBOSE=true |
4. 高級/特殊
CURLOPT_SSLCERT/CURLOPT_SSLKEY/CURLOPT_SSLCERTPASSWD：客戶端證書雙向 TLS。CURLOPT_CAINFO/CURLOPT_CAPATH：自定義 CA 憑證包路徑。CURLOPT_ENCODING：'' 啟用所有內建解碼 (gzip, deflate, br, zstd)。CURLOPT_RESOLVE：['example.com:443:1.2.3.4'] 手動解析，繞過 DNS/測試新 IP。CURLOPT_UNIX_SOCKET_PATH：走 Unix Domain Socket 訪問本地服務。CURLOPT_HAPROXYPROTOCOL：發送 HAProxy PROXY protocol v1 頭。
高頻誤區與最佳實踐
CURLOPT_POSTFIELDS 陣列 vs 字符串：傳陣列強制 multipart/form-data (含文件上傳需 CURLFile)；傳 JSON 字符串需手動 json_encode + 設置 Content-Type: application/json。- 重用 Handle 時未重置選項：
curl_setopt_array($ch, [...]) 或逐個 curl_setopt 覆蓋，避免上次請求的 Header/Cookie 殘留。
- 忽略
CURLOPT_SSL_VERIFYPEER：生產環境 絕不可設為 false，若憑證信任鏈不全，請補全 CA 或使用 CURLOPT_CAINFO 指定合法 CA 文件。
- 超時設置不全：必須同時設置
CURLOPT_CONNECTTIMEOUT 和 CURLOPT_TIMEOUT，否則可能無限阻塞。
- 未檢查
curl_errno()：HTTP 200 但 cURL 錯誤碼非 0 表示傳輸層失敗（如 TLS 握手失敗、連接重置）。
- 大文件下載未用流式寫入：
CURLOPT_RETURNTRANSFER 會將整個響應體載入內存，GB 級文件直接 OOM。必須用 CURLOPT_WRITEFUNCTION + 文件句柄。
- 並發場景未使用
curl_multi 或 Swoole 協程：串行請求無法滿足高吞吐需求。
調試三件套
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_VERBOSE, true);
curl_setopt($ch, CURLOPT_STDERR, $fp = fopen('php://temp', 'rw'));
curl_exec($ch);
rewind($fp);
echo stream_get_contents($fp); // 輸出完整 TLS 握手、請求/響應頭、數據流向
fclose($fp);
或使用 curl_getinfo($ch, CURLINFO_*) 獲取精確耗時：CURLINFO_TOTAL_TIME, CURLINFO_NAMELOOKUP_TIME, CURLINFO_CONNECT_TIME, CURLINFO_PRETRANSFER_TIME, CURLINFO_STARTTRANSFER_TIME, CURLINFO_REDIRECT_TIME。
