萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> PHP 程式設計

PHP cURL 選項完整參考手冊 (分類詳解)

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_FAILONERRORHTTP ≥400 視為失敗,回傳 false
CURLOPT_FILETIME嘗試取得遠端檔案修改時間 (curl_getinfo CURLINFO_FILETIME)
CURLOPT_FOLLOWLOCATION遞迴跟隨 Location 重導向 (受 MAXREDIRS 限制)
CURLOPT_FORBID_REUSE完成後強制關閉連線,不重用
CURLOPT_FRESH_CONNECT強制建立新連線,不使用連線池
CURLOPT_FTP_USE_EPRTFTP 使用 EPRT/LPRT 指令 (FALSE 則用 PORT)
CURLOPT_FTP_USE_EPSVFTP 嘗試 EPSV 後再退回 PASV
CURLOPT_FTPAPPENDFTP 上傳採附加模式而非覆蓋
CURLOPT_FTPASCIIFTP 使用 ASCII 模式 (CURLOPT_TRANSFERTEXT 別名)
CURLOPT_FTPLISTONLYFTP 僅列出目錄名稱
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_PUTHTTP PUT 上傳 (需搭配 INFILE/INFILESIZE)
CURLOPT_RETURNTRANSFER回傳字串而非直接輸出 (最常用)
CURLOPT_SSL_VERIFYPEER驗證對端 SSL 憑證 (生產必 TRUE),配合 CAINFO/CAPATH
CURLOPT_TRANSFERTEXTFTP 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_TIMEOUTDNS 快取秒數 (預設 120)
CURLOPT_FTPSSLAUTHFTP SSL 驗證方式 (CURLFTPAUTH_SSL/TLS/DEFAULT)
CURLOPT_HTTP_VERSIONCURL_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_PROXYAUTHProxy 驗證方式 (BASIC|NTLM)
CURLOPT_PROXYPORTProxy 埠號
CURLOPT_PROXYTYPECURLPROXY_HTTP (預設) | CURLPROXY_SOCKS5
CURLOPT_REDIR_PROTOCOLS重導向允許協定位元遮罩 (7.19.4+)
CURLOPT_RESUME_FROM斷點續傳起始位移 (bytes)
CURLOPT_SSL_VERIFYHOST0=不驗證, 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_CAINFOCA 憑證束檔案路徑 (PEM 格式)
CURLOPT_CAPATHCA 憑證目錄 (需經 c_rehash 處理)
CURLOPT_COOKIE請求攜帶 Cookie 字串
CURLOPT_COOKIEFILE讀取 Cookie 檔案 (啟用 Cookie Engine)
CURLOPT_COOKIEJAR儲存 Cookie 檔案 (關閉時寫入)
CURLOPT_CUSTOMREQUEST自定 HTTP Method (PUT, DELETE, PATCH 等)
CURLOPT_EGDSOCKETEGD socket 路徑 (entropy)
CURLOPT_ENCODINGAccept-Encoding 值 (如 "gzip, deflate"),空字串支援所有
CURLOPT_FTPPORTFTP PORT 指令 IP
CURLOPT_INTERFACE綁定本地網卡介面 (IP/介面名)
CURLOPT_KRB4LEVELKerberos 4 安全等級
CURLOPT_LOGIN_OPTIONS登入選項 (IMAP/POP3/SMTP)
CURLOPT_PINNEDPUBLICKEY公鑰釘選 (SHA256 base64)
CURLOPT_POSTFIELDSPOST 資料 (陣列/字串/CURLFile)
CURLOPT_PROXYProxy 伺服器 host:port
CURLOPT_PROXYUSERPWDProxy 認證 user:pwd
CURLOPT_RANDOM_FILESSL 隨機種子檔案
CURLOPT_RANGERange 標頭值 (如 "0-499")
CURLOPT_REFERERReferer 標頭
CURLOPT_SERVICE_NAMEKerberos/SPI 服務名稱
CURLOPT_SSLCERT客戶端證書檔案 (PEM)
CURLOPT_SSLCERTPASSWD客戶端證書密碼
CURLOPT_SSLCERTTYPE證書類型 (PEM/DER/ENG)
CURLOPT_SSLKEY私鑰檔案
CURLOPT_SSLKEYPASSWD私鑰密碼
CURLOPT_SSLKEYTYPE私鑰類型 (PEM/DER/ENG)
CURLOPT_SSLENGINEOpenSSL 引擎 ID
CURLOPT_SSLENGINE_DEFAULT設定為預設引擎
CURLOPT_URL請求 URL (必填)
CURLOPT_USERAGENTUser-Agent 字串
CURLOPT_USERNAME驗證用戶名
CURLOPT_PASSWORD驗證密碼
CURLOPT_XOAUTH2_BEAREROAuth 2.0 Bearer Token

四、回呼/資源/陣列選項

選項類型說明
CURLOPT_PROGRESSFUNCTIONcallable進度回呼 fn($ch, $dltotal, $dlnow, $ultotal, $ulnow): int 返回非 0 中止
CURLOPT_READFUNCTIONcallable讀取上傳資料回呼 fn($ch, $fd, $length): string
CURLOPT_WRITEFUNCTIONcallable寫入回應資料回呼 fn($ch, $data): int 返回寫入長度
CURLOPT_HEADERFUNCTIONcallable處理回應標頭行回呼 fn($ch, $header): int
CURLOPT_DEBUGDATAmixed傳遞給 DEBUGFUNCTION 的資料
CURLOPT_DEBUGFUNCTIONcallable除錯回呼 fn($ch, $type, $data): int
CURLOPT_STDERRresource錯誤/詳細輸出導向的檔案指標
CURLOPT_INFILEresource上傳輸入檔案指標 (配合 PUT/UPLOAD)
CURLOPT_FILEresource輸出寫入檔案指標 (預設 STDOUT)
CURLOPT_WRITEHEADERresource標頭寫入檔案指標
CURLOPT_HTTP200ALIASESarray視為成功的 HTTP 狀態碼陣列
CURLOPT_HTTPHEADERarray自定請求標頭陣列
CURLOPT_POSTQUOTEarrayFTP 傳輸後執行指令陣列
CURLOPT_PREQUOTEarrayFTP 傳輸前執行指令陣列
CURLOPT_QUOTEarrayFTP 傳輸中執行指令陣列
CURLOPT_RESOLVEarray自定義 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);
?>
copyright © 萬盛學電腦網 all rights reserved