cURL 訪問 HTTPS 時的 SSL 驗證機制直接關係資料傳輸安全性。本文詳細解析三種驗證等級、CA 憑證部署、自簽憑證處理、常見錯誤代碼與排查流程,附生產級封裝函數。
| 等級 | CURLOPT_SSL_VERIFYPEER | CURLOPT_SSL_VERIFYHOST | CURLOPT_CAINFO | 安全性 | 適用場景 |
|---|---|---|---|---|---|
| 嚴格驗證 | true | 2 | CA 憑證路徑 | 最高 | 生產環境、金融/支付/個資介接 |
| 僅驗證域名 | false | 1 | 不需要 | 低 | 測試環境、自簽憑證、內網服務 |
| 完全不驗證 | false | 0 | 不需要 | 極低(中間人攻擊風險) | 極特殊測試、除錯臨時用 |
<?php
/**
* cURL HTTPS POST 請求(支援嚴格/寬鬆驗證模式)
* @param string $url 目標 URL
* @param array $data POST 欄位
* @param int $timeout 總超時秒數
* @param bool $strictSSL true=嚴格驗證CA+域名, false=僅驗證域名存在
* @param string|null $caPath CA 憑證路徑,null=自動尋找
* @return string|false 回應內容或失敗
*/
function curlHttpsPost(
string $url,
array $data = [],
int $timeout = 30,
bool $strictSSL = true,
?string $caPath = null
): string|false {
// 自動尋找 CA 憑證
if ($caPath === null) {
$candidates = [
'/etc/ssl/certs/ca-certificates.crt', // Debian/Ubuntu
'/etc/pki/tls/certs/ca-bundle.crt', // RHEL/CentOS
'/usr/local/ssl/certs/ca-bundle.crt', // 自編譯 OpenSSL
__DIR__ . '/cacert.pem', // 專案自帶
];
foreach ($candidates as $path) {
if (is_file($path)) { $caPath = $path; break; }
}
}
$ch = curl_init($url);
$options = [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $data,
CURLOPT_TIMEOUT => $timeout,
CURLOPT_CONNECTTIMEOUT => min(10, $timeout - 1),
CURLOPT_HTTPHEADER => ['Expect:'], // 避免 100-continue 延遲
CURLOPT_USERAGENT => 'PHP cURL/' . PHP_VERSION,
];
if (str_starts_with($url, 'https://')) {
if ($strictSSL) {
$options[CURLOPT_SSL_VERIFYPEER] = true;
$options[CURLOPT_SSL_VERIFYHOST] = 2;
if ($caPath) $options[CURLOPT_CAINFO] = $caPath;
} else {
$options[CURLOPT_SSL_VERIFYPEER] = false;
$options[CURLOPT_SSL_VERIFYHOST] = 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) {
error_log("cURL 錯誤 [$errno]: $error | URL: $url");
return false;
}
if ($httpCode >= 400) {
error_log("HTTP $httpCode | URL: $url | Response: " . mb_substr($response, 0, 500));
return false;
}
return $response;
}
# 官方來源(Mozilla 信任庫)
wget https://curl.se/ca/cacert.pem -O /etc/ssl/certs/ca-certificates.crt
# 或專案目錄
wget https://curl.se/ca/cacert.pem -O /var/www/project/cacert.pem
# crontab -e
0 3 1 * * wget -q https://curl.se/ca/cacert.pem -O /etc/ssl/certs/ca-certificates.crt && systemctl reload php-fpm
選項一:將自簽 CA 加入系統信任庫
cp my-ca.crt /usr/local/share/ca-certificates/
update-ca-certificates
選項二:指定單一憑證檔
curl_setopt($ch, CURLOPT_CAINFO, '/path/to/my-ca.crt');
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 2);
選項三:針對特定主機跳過驗證(僅測試)
$insecureHosts = ['dev.internal', 'test.local'];
if (in_array(parse_url($url, PHP_URL_HOST), $insecureHosts)) {
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 1);
}
| 錯誤代碼 | 常數 | 原因 | 解決 |
|---|---|---|---|
| 60 | CURLE_SSL_CACERT | CA 憑證找不到/驗證失敗 | 配置 CURLOPT_CAINFO、更新 ca-bundle |
| 51 | CURLE_SSL_ENGINE_NOTFOUND | SSL 引擎不支援 | 重裝 libcurl/openssl |
| 35 | CURLE_SSL_CONNECT_ERROR | SSL 連線協商失敗 | 檢查 TLS 版本支援、憑證過期、SNI 設定 |
| 28 | CURLE_OPERATION_TIMEDOUT | 連線/傳輸超時 | 調大 timeout、檢查防火牆/網路 |
| 7 | CURLE_COULDNT_CONNECT | 無法連線主機 | DNS/防火牆/IP 封鎖 |
| 56 | CURLE_RECV_ERROR | 接收資料失敗 | 網路不穩、伺服器斷連 |
<?php
// 開啟詳細除錯輸出
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_VERBOSE, true);
$verbose = fopen('php://temp', 'rw+');
curl_setopt($ch, CURLOPT_STDERR, $verbose);
curl_exec($ch);
rewind($verbose);
echo stream_get_contents($verbose); // 印出完整 TLS 交握過程
fclose($verbose);