您现在的位置：程式碼之家 >> 編程語言 > >> 網頁程式設計 >> PHP 程式設計 >> PHP 綜合知識

PHP cURL 選項完整參考手冊（按參數類型分類）

編輯：PHP 綜合知識

分類說明

cURL 選項按 curl_setopt($ch, OPTION, VALUE) 中 VALUE 的資料型別分為五大類：布林、整數、字串、陣列、資源/回調。本文整理官方常用選項，附中文備註與版本資訊。

一、布林值選項（VALUE = true/false）

常數	作用	備註
`CURLOPT_AUTOREFERER`	重定向時自動帶 Referer
`CURLOPT_BINARYTRANSFER`	配合 RETURNTRANSFER 回傳原始二進位
`CURLOPT_COOKIESESSION`	僅傳送 Session Cookie，忽略持久 Cookie
`CURLOPT_CRLF`	Unix 換行 `\n` 轉 `\r\n`
`CURLOPT_DNS_USE_GLOBAL_CACHE`	啟用全域 DNS 快取（執行緒安全）	預設開啟
`CURLOPT_FAILONERROR`	HTTP 狀態碼 ≥ 400 視為失敗	預設忽略
`CURLOPT_FILETIME`	嘗試取得遠端檔案修改時間	透過 `curl_getinfo(CURLINFO_FILETIME)` 取得
`CURLOPT_FOLLOWLOCATION`	自動追蹤 Location 重定向	配合 `CURLOPT_MAXREDIRS` 限制層數
`CURLOPT_FORBID_REUSE`	完成後強制關閉連線，不重用
`CURLOPT_FRESH_CONNECT`	強制建立新連線，不使用連線池
`CURLOPT_FTP_USE_EPRT`	FTP 使用 EPRT/LPRT 指令	false 則用 PORT
`CURLOPT_FTP_USE_EPSV`	FTP 優先嘗試 EPSV	false 禁用
`CURLOPT_FTPAPPEND`	FTP 上傳採追加模式
`CURLOPT_FTPASCII`	FTP ASCII 模式傳輸	同 `CURLOPT_TRANSFERTEXT`
`CURLOPT_FTPLISTONLY`	FTP 僅列出目錄名稱
`CURLOPT_HEADER`	輸出包含 Header
`CURLINFO_HEADER_OUT`	記錄發送的請求 Header 字串	PHP 5.1.3+，供除錯
`CURLOPT_HTTPGET`	強制 GET 方法	預設即 GET
`CURLOPT_HTTPPROXYTUNNEL`	透過 HTTP Proxy 通道傳輸
`CURLOPT_MUTE`	重設所有選項為預設值
`CURLOPT_NETRC`	從 `~/.netrc` 讀取帳密
`CURLOPT_NOBODY`	不輸出 Body（HEAD 請求）
`CURLOPT_NOPROGRESS`	關閉進度條	預設 true，僅除錯時改 false
`CURLOPT_NOSIGNAL`	忽略 cURL 發給 PHP 的訊號	多執行緒 SAPI 預設開啟
`CURLOPT_POST`	發送 POST 請求	Content-Type: application/x-www-form-urlencoded
`CURLOPT_PUT`	啟用 HTTP PUT 上傳	需配合 `INFILE`/`INFILESIZE`
`CURLOPT_RETURNTRANSFER`	回傳字串而非直接輸出	最常用
`CURLOPT_SSL_VERIFYPEER`	驗證 Peer 憑證	生產環境建議 true，配合 CAINFO
`CURLOPT_TRANSFERTEXT`	FTP/ASCII 模式	Windows 下 STDOUT 不會設 binary
`CURLOPT_UNRESTRICTED_AUTH`	重定向時保持認證資訊跨域傳送
`CURLOPT_UPLOAD`	啟用上傳模式
`CURLOPT_VERBOSE`	輸出詳細除錯資訊到 STDERR

二、整數值選項

常數	作用	備註
`CURLOPT_BUFFERSIZE`	讀取緩衝區大小	cURL 7.10+
`CURLOPT_CLOSEPOLICY`	連線關閉策略	目前僅支援 LEAST_RECENTLY_USED / OLDEST
`CURLOPT_CONNECTTIMEOUT`	連線階段逾時（秒）	0 = 無限等待
`CURLOPT_CONNECTTIMEOUT_MS`	連線逾時（毫秒）	cURL 7.16.2+, PHP 5.2.3+
`CURLOPT_DNS_CACHE_TIMEOUT`	DNS 快取壽命（秒）	預設 120
`CURLOPT_FTPSSLAUTH`	FTP SSL 驗證方式	SSL/TLS/DEFAULT
`CURLOPT_HTTP_VERSION`	強制 HTTP 版本	NONE/1.0/1.1
`CURLOPT_HTTPAUTH`	HTTP 認證方法位元遮罩	BASIC\|DIGEST\|GSSNEGOTIATE\|NTLM\|ANY\|ANYSAFE
`CURLOPT_INFILESIZE`	上傳檔案大小限制（Bytes）
`CURLOPT_LOW_SPEED_LIMIT`	低速門檻	配合 LOW_SPEED_TIME 判斷中斷
`CURLOPT_LOW_SPEED_TIME`	低速持續秒數
`CURLOPT_MAXCONNECTS`	最大連線數	超過依 CLOSEPOLICY 關閉
`CURLOPT_MAXREDIRS`	最大重定向次數	配合 FOLLOWLOCATION
`CURLOPT_PORT`	指定連接埠	可選
`CURLOPT_PROTOCOLS`	允許使用的協議位元遮罩	HTTP/HTTPS/FTP/FTPS/SCP/SFTP/...
`CURLOPT_PROXYAUTH`	Proxy 認證方法	僅 BASIC/NTLM
`CURLOPT_PROXYPORT`	Proxy 連接埠
`CURLOPT_PROXYTYPE`	Proxy 類型	HTTP (預設) / SOCKS5
`CURLOPT_REDIR_PROTOCOLS`	重定向允許的協議	預設除 FILE/SCP 外全開
`CURLOPT_RESUME_FROM`	斷點續傳位移（Bytes）
`CURLOPT_SSL_VERIFYHOST`	驗證 SSL Common Name	1=存在/2=存在且匹配主機名
`CURLOPT_SSLVERSION`	指定 SSL 版本	2/3/TLSv1，預設自動協商
`CURLOPT_TIMECONDITION`	時間條件模式	IFMODSINCE/IFUNMODSINCE
`CURLOPT_TIMEOUT`	總執行逾時（秒）
`CURLOPT_TIMEOUT_MS`	總執行逾時（毫秒）	cURL 7.16.2+, PHP 5.2.3+
`CURLOPT_TIMEVALUE`	時間條件用的時間戳

三、字串值選項

常數	作用	備註
`CURLOPT_CAINFO`	CA 憑證檔路徑	配合 SSL_VERIFYPEER
`CURLOPT_CAPATH`	CA 憑證目錄
`CURLOPT_COOKIE`	手動設定 Cookie 字串	`name=val; name2=val2`
`CURLOPT_COOKIEFILE`	讀取 Cookie 檔	Netscape 格式或純 Header
`CURLOPT_COOKIEJAR`	寫入 Cookie 檔	連線結束時儲存
`CURLOPT_CUSTOMREQUEST`	自定義 HTTP Method	`DELETE`, `PATCH` 等，勿填完整請求行
`CURLOPT_EGDSOCKET`	EGD Socket 路徑	類似 RANDOM_FILE
`CURLOPT_ENCODING`	Accept-Encoding	`identity, deflate, gzip`，空字串=全支援
`CURLOPT_FTPPORT`	FTP PORT 指令用 IP	IP/主機名/介面名/-
`CURLOPT_INTERFACE`	出網介面/IP/主機名
`CURLOPT_KRB4LEVEL`	Kerberos 4 安全等級	clear/safe/confidential/private
`CURLOPT_POSTFIELDS`	POST 資料	字串 `a=1&b=2` 或陣列（自動 multipart/form-data）
`CURLOPT_PROXY`	HTTP Proxy 位址	`host:port`
`CURLOPT_PROXYUSERPWD`	Proxy 帳密	`user:pass`
`CURLOPT_RANDOM_FILE`	SSL 隨機種子檔
`CURLOPT_RANGE`	Range 請求範圍	`X-Y` 或 `X-Y,N-M`
`CURLOPT_REFERER`	Referer Header
`CURLOPT_SSL_CIPHER_LIST`	SSL 加密套件列表	`RC4-SHA:TLSv1`
`CURLOPT_SSLCERT`	客戶端憑證檔 (PEM)
`CURLOPT_SSLCERTPASSWD`	客戶端憑證密碼
`CURLOPT_SSLCERTTYPE`	憑證格式	PEM/DER/ENG
`CURLOPT_SSLENGINE`	SSL 引擎名稱
`CURLOPT_SSLENGINE_DEFAULT`	設為預設非對稱加密引擎
`CURLOPT_SSLKEY`	私鑰檔
`CURLOPT_SSLKEYPASSWD`	私鑰密碼	敏感資訊，注意腳本權限
`CURLOPT_SSLKEYTYPE`	私鑰格式	PEM/DER/ENG
`CURLOPT_URL`	目標 URL	也可在 `curl_init()` 給定
`CURLOPT_USERAGENT`	User-Agent 字串
`CURLOPT_USERPWD`	HTTP 認證帳密	`user:pass`

四、陣列值選項

常數	作用	備註
`CURLOPT_HTTP200ALIASES`	視為成功的 HTTP 狀態碼陣列	cURL 7.10.3+
`CURLOPT_HTTPHEADER`	自定義請求 Header 陣列	`['Content-Type: application/json', 'Authorization: Bearer xxx']`
`CURLOPT_POSTQUOTE`	FTP 傳輸後執行的指令陣列
`CURLOPT_QUOTE`	FTP 傳輸前執行的指令陣列

五、資源型別選項（需 `fopen()` 回傳的 handle）

常數	作用	預設
`CURLOPT_FILE`	輸出寫入檔案	STDOUT
`CURLOPT_INFILE`	上傳讀取檔案	—
`CURLOPT_STDERR`	錯誤輸出導向	STDERR
`CURLOPT_WRITEHEADER`	Header 寫入檔案	—

六、回調函數選項

常數	回調簽名	回傳值	用途
`CURLOPT_HEADERFUNCTION`	`fn($ch, $headerStr) : int`	已寫入長度	自行處理 Header
`CURLOPT_PASSWDFUNCTION`	`fn($ch, $prompt, $maxLen) : string`	密碼字串	互動式取密碼
`CURLOPT_PROGRESSFUNCTION`	`fn($ch, $dlTotal, $dlNow, $ulTotal, $ulNow) : int`	0 繼續 / 非 0 中止	進度條
`CURLOPT_READFUNCTION`	`fn($ch, $fd, $length) : string`	資料字串，空=EOF	自定義讀取上傳資料
`CURLOPT_WRITEFUNCTION`	`fn($ch, $data) : int`	已寫入長度	自行處理 Body（流式處理大檔案）

常用組合範例

<?php
$ch = curl_init('https://api.example.com/users');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 10,
    CURLOPT_CONNECTTIMEOUT => 5,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $token, 'Accept: application/json'],
    CURLOPT_SSL_VERIFYPEER => true,
    CURLOPT_SSL_VERIFYHOST => 2,
    CURLOPT_CAINFO         => __DIR__ . '/cacert.pem',
]);
$resp = curl_exec($ch);
if ($resp === false) {
    throw new Exception(curl_error($ch), curl_errno($ch));
}
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
?>