萬盛學電腦網

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

PHP cURL 訪問 HTTPS 完整指南:SSL 驗證等級、CA 憑證配置與常見錯誤排查

cURL 訪問 HTTPS 時的 SSL 驗證機制直接關係資料傳輸安全性。本文詳細解析三種驗證等級、CA 憑證部署、自簽憑證處理、常見錯誤代碼與排查流程,附生產級封裝函數。

SSL 驗證三種等級

等級CURLOPT_SSL_VERIFYPEERCURLOPT_SSL_VERIFYHOSTCURLOPT_CAINFO安全性適用場景
嚴格驗證true2CA 憑證路徑最高生產環境、金融/支付/個資介接
僅驗證域名false1不需要低測試環境、自簽憑證、內網服務
完全不驗證false0不需要極低(中間人攻擊風險)極特殊測試、除錯臨時用

生產級封裝函數

<?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;
}

CA 憑證部署指南

下載最新 CA Bundle

# 官方來源(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);
}

常見錯誤代碼速查

錯誤代碼常數原因解決
60CURLE_SSL_CACERTCA 憑證找不到/驗證失敗配置 CURLOPT_CAINFO、更新 ca-bundle
51CURLE_SSL_ENGINE_NOTFOUNDSSL 引擎不支援重裝 libcurl/openssl
35CURLE_SSL_CONNECT_ERRORSSL 連線協商失敗檢查 TLS 版本支援、憑證過期、SNI 設定
28CURLE_OPERATION_TIMEDOUT連線/傳輸超時調大 timeout、檢查防火牆/網路
7CURLE_COULDNT_CONNECT無法連線主機DNS/防火牆/IP 封鎖
56CURLE_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);
copyright © 萬盛學電腦網 all rights reserved