cURL 選項分類總覽
curl_setopt($ch, $option, $value) 中 $option 依值類型分為布林、整數、字串、陣列/資源/回呼函式。以下為核心選項分類說明 (基於 libcurl 7.x)。
一、布林值選項 (TRUE/FALSE)
| 選項 | 說明 |
| CURLOPT_AUTOREFERER | 自動設定 Referer 隨重導向 |
| CURLOPT_BINARYTRANSFER | 配合 RETURNTRANSFER 回傳原始二進位資料 |
| CURLOPT_COOKIESESSION | 僅傳送 Session Cookie,忽略持久 Cookie |
| CURLOPT_CRLF | 將 LF 轉換為 CRLF |
| CURLOPT_DNS_USE_GLOBAL_CACHE | 啟用全域 DNS 快取 (線程安全,預設開啟) |
| CURLOPT_FAILONERROR | HTTP ≥400 視為失敗,回傳 false |
| CURLOPT_FILETIME | 嘗試取得遠端檔案修改時間 (curl_getinfo CURLINFO_FILETIME) |
| CURLOPT_FOLLOWLOCATION | 遞迴跟隨 Location 重導向 (受 MAXREDIRS 限制) |
| CURLOPT_FORBID_REUSE | 完成後強制關閉連線,不重用 |
| CURLOPT_FRESH_CONNECT | 強制建立新連線,不使用連線池 |
| CURLOPT_FTP_USE_EPRT | FTP 使用 EPRT/LPRT 指令 (FALSE 則用 PORT) |
| CURLOPT_FTP_USE_EPSV | FTP 嘗試 EPSV 後再退回 PASV |
| CURLOPT_FTPAPPEND | FTP 上傳採附加模式而非覆蓋 |
| CURLOPT_FTPASCII | FTP 使用 ASCII 模式 (CURLOPT_TRANSFERTEXT 別名) |
| CURLOPT_FTPLISTONLY | FTP 僅列出目錄名稱 |
| CURLOPT_HEADER | 輸出包含回應標頭 |
| CURLINFO_HEADER_OUT | 追蹤請求字串 (PHP 5.1.3+),curl_getinfo($ch, CURLINFO_HEADER_OUT) |
| CURLOPT_HTTPGET | 強制 HTTP GET (預設即為 GET) |
| CURLOPT_HTTPPROXYTUNNEL | 透過 HTTP Proxy 建立隧道 |
| CURLOPT_MUTE | 重置所有修改選項為預設值 (已棄用) |
| CURLOPT_NETRC | 從 ~/.netrc 讀取帳密 |
| CURLOPT_NOBODY | 不輸出 Body (HEAD 請求) |
| CURLOPT_NOPROGRESS | 關閉進度回呼 (預設 TRUE,僅除錯時改 FALSE) |
| CURLOPT_NOSIGNAL | 多線程環境忽略信號 (SAPI 多線程預設開啟) |
| CURLOPT_POST | 發送一般 POST (application/x-www-form-urlencoded) |
| CURLOPT_PUT | HTTP PUT 上傳 (需搭配 INFILE/INFILESIZE) |
| CURLOPT_RETURNTRANSFER | 回傳字串而非直接輸出 (最常用) |
| CURLOPT_SSL_VERIFYPEER | 驗證對端 SSL 憑證 (生產必 TRUE),配合 CAINFO/CAPATH |
| CURLOPT_TRANSFERTEXT | FTP ASCII 模式 / LDAP 純文字 |
| CURLOPT_UNRESTRICTED_AUTH | 重導向時保持認證資訊跨域傳送 |
| CURLOPT_UPLOAD | 啟用上傳模式 |
| CURLOPT_VERBOSE | 輸出詳細除錯資訊至 STDERR 或 CURLOPT_STDERR |
二、整數值選項
| 選項 | 說明 |
| CURLOPT_BUFFERSIZE | 讀取緩衝區大小 (不保證填滿) |
| CURLOPT_CLOSEPOLICY | 連線關閉策略 (CURLCLOSEPOLICY_*,支援度有限) |
| CURLOPT_CONNECTTIMEOUT | 建立連線逾時秒數 (0=無限) |
| CURLOPT_CONNECTTIMEOUT_MS | 建立連線逾時毫秒 (7.16.2+, PHP 5.2.3+) |
| CURLOPT_DNS_CACHE_TIMEOUT | DNS 快取秒數 (預設 120) |
| CURLOPT_FTPSSLAUTH | FTP SSL 驗證方式 (CURLFTPAUTH_SSL/TLS/DEFAULT) |
| CURLOPT_HTTP_VERSION | CURL_HTTP_VERSION_NONE/1_0/1_1 |
| CURLOPT_HTTPAUTH | 驗證方式位元遮罩 (BASIC|DIGEST|GSSNEGOTIATE|NTLM|ANY|ANYSAFE) |
| CURLOPT_INFILESIZE | 上傳檔案大小限制 (bytes) |
| CURLOPT_LOW_SPEED_LIMIT | 低速門檻 (bytes/sec),配合 LOW_SPEED_TIME 判斷中止 |
| CURLOPT_LOW_SPEED_TIME | 持續低速秒數,超過則中止 |
| CURLOPT_MAXCONNECTS | 最大連線數,超過依 CLOSEPOLICY 關閉 |
| CURLOPT_MAXREDIRS | 最大重導向次數 (配合 FOLLOWLOCATION) |
| CURLOPT_PORT | 指定連線埠 (可選,通常在 URL 指定) |
| CURLOPT_PROTOCOLS | 允許協定位元遮罩 (CURLPROTO_HTTP|HTTPS|FTP|FTPS|SCP|SFTP|TELNET|LDAP|LDAPS|DICT|FILE|TFTP|ALL) |
| CURLOPT_PROXYAUTH | Proxy 驗證方式 (BASIC|NTLM) |
| CURLOPT_PROXYPORT | Proxy 埠號 |
| CURLOPT_PROXYTYPE | CURLPROXY_HTTP (預設) | CURLPROXY_SOCKS5 |
| CURLOPT_REDIR_PROTOCOLS | 重導向允許協定位元遮罩 (7.19.4+) |
| CURLOPT_RESUME_FROM | 斷點續傳起始位移 (bytes) |
| CURLOPT_SSL_VERIFYHOST | 0=不驗證, 1=檢查存在, 2=驗證匹配主機名 (預設 2) |
| CURLOPT_SSLVERSION | 指定 SSL/TLS 版本 (CURL_SSLVERSION_TLSv1_2 等) |
| CURLOPT_TIMECONDITION | 時間條件模式 (CURL_TIMECOND_IFMODSINCE/IFUNMODSINCE) |
| CURLOPT_TIMEOUT | 總執行逾時秒數 |
| CURLOPT_TIMEOUT_MS | 總執行逾時毫秒 (7.16.2+) |
| CURLOPT_TIMEVALUE | 配合 TIMECONDITION 的時間戳 |
三、字串值選項
| 選項 | 說明 |
| CURLOPT_CAINFO | CA 憑證束檔案路徑 (PEM 格式) |
| CURLOPT_CAPATH | CA 憑證目錄 (需經 c_rehash 處理) |
| CURLOPT_COOKIE | 請求攜帶 Cookie 字串 |
| CURLOPT_COOKIEFILE | 讀取 Cookie 檔案 (啟用 Cookie Engine) |
| CURLOPT_COOKIEJAR | 儲存 Cookie 檔案 (關閉時寫入) |
| CURLOPT_CUSTOMREQUEST | 自定 HTTP Method (PUT, DELETE, PATCH 等) |
| CURLOPT_EGDSOCKET | EGD socket 路徑 (entropy) |
| CURLOPT_ENCODING | Accept-Encoding 值 (如 "gzip, deflate"),空字串支援所有 |
| CURLOPT_FTPPORT | FTP PORT 指令 IP |
| CURLOPT_INTERFACE | 綁定本地網卡介面 (IP/介面名) |
| CURLOPT_KRB4LEVEL | Kerberos 4 安全等級 |
| CURLOPT_LOGIN_OPTIONS | 登入選項 (IMAP/POP3/SMTP) |
| CURLOPT_PINNEDPUBLICKEY | 公鑰釘選 (SHA256 base64) |
| CURLOPT_POSTFIELDS | POST 資料 (陣列/字串/CURLFile) |
| CURLOPT_PROXY | Proxy 伺服器 host:port |
| CURLOPT_PROXYUSERPWD | Proxy 認證 user:pwd |
| CURLOPT_RANDOM_FILE | SSL 隨機種子檔案 |
| CURLOPT_RANGE | Range 標頭值 (如 "0-499") |
| CURLOPT_REFERER | Referer 標頭 |
| CURLOPT_SERVICE_NAME | Kerberos/SPI 服務名稱 |
| CURLOPT_SSLCERT | 客戶端證書檔案 (PEM) |
| CURLOPT_SSLCERTPASSWD | 客戶端證書密碼 |
| CURLOPT_SSLCERTTYPE | 證書類型 (PEM/DER/ENG) |
| CURLOPT_SSLKEY | 私鑰檔案 |
| CURLOPT_SSLKEYPASSWD | 私鑰密碼 |
| CURLOPT_SSLKEYTYPE | 私鑰類型 (PEM/DER/ENG) |
| CURLOPT_SSLENGINE | OpenSSL 引擎 ID |
| CURLOPT_SSLENGINE_DEFAULT | 設定為預設引擎 |
| CURLOPT_URL | 請求 URL (必填) |
| CURLOPT_USERAGENT | User-Agent 字串 |
| CURLOPT_USERNAME | 驗證用戶名 |
| CURLOPT_PASSWORD | 驗證密碼 |
| CURLOPT_XOAUTH2_BEARER | OAuth 2.0 Bearer Token |
四、回呼/資源/陣列選項
| 選項 | 類型 | 說明 |
| CURLOPT_PROGRESSFUNCTION | callable | 進度回呼 fn($ch, $dltotal, $dlnow, $ultotal, $ulnow): int 返回非 0 中止 |
| CURLOPT_READFUNCTION | callable | 讀取上傳資料回呼 fn($ch, $fd, $length): string |
| CURLOPT_WRITEFUNCTION | callable | 寫入回應資料回呼 fn($ch, $data): int 返回寫入長度 |
| CURLOPT_HEADERFUNCTION | callable | 處理回應標頭行回呼 fn($ch, $header): int |
| CURLOPT_DEBUGDATA | mixed | 傳遞給 DEBUGFUNCTION 的資料 |
| CURLOPT_DEBUGFUNCTION | callable | 除錯回呼 fn($ch, $type, $data): int |
| CURLOPT_STDERR | resource | 錯誤/詳細輸出導向的檔案指標 |
| CURLOPT_INFILE | resource | 上傳輸入檔案指標 (配合 PUT/UPLOAD) |
| CURLOPT_FILE | resource | 輸出寫入檔案指標 (預設 STDOUT) |
| CURLOPT_WRITEHEADER | resource | 標頭寫入檔案指標 |
| CURLOPT_HTTP200ALIASES | array | 視為成功的 HTTP 狀態碼陣列 |
| CURLOPT_HTTPHEADER | array | 自定請求標頭陣列 |
| CURLOPT_POSTQUOTE | array | FTP 傳輸後執行指令陣列 |
| CURLOPT_PREQUOTE | array | FTP 傳輸前執行指令陣列 |
| CURLOPT_QUOTE | array | FTP 傳輸中執行指令陣列 |
| CURLOPT_RESOLVE | array | 自定義 DNS 解析 ["host:port:ip", ...] (7.21.3+) |
實用組合範例
<?php
// 安全、高效、可除錯的預設組合
$defaults = [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_MAXREDIRS => 5,
CURLOPT_CONNECTTIMEOUT => 5,
CURLOPT_TIMEOUT => 30,
CURLOPT_SSL_VERIFYPEER => true,
CURLOPT_SSL_VERIFYHOST => 2,
CURLOPT_ENCODING => 'gzip, deflate',
CURLOPT_USERAGENT => 'MyApp/1.0 (+https://example.com/bot)',
CURLOPT_NOSIGNAL => true, // 多線程環境必開
];
$ch = curl_init($url);
curl_setopt_array($ch, $defaults);
// 針對性覆蓋...
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$resp = curl_exec($ch);
?>