在微服務架構與第三方 API 整合場景中,cURL 是跨伺服器通訊的首選。本文分享實戰封裝模式、效能優化技巧與擴展安裝排錯指南。
function postRemote(string $url, array $data, int $timeout = 30): ?string {
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $data,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => $timeout,
CURLOPT_HEADER => false,
CURLOPT_SSL_VERIFYPEER => true,
]);
$response = curl_exec($ch);
if (curl_errno($ch)) {
error_log("cURL POST Error: " . curl_error($ch));
curl_close($ch);
return null;
}
curl_close($ch);
return $response;
}
function getRemote(string $url, int $timeout = 10): ?string {
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => $timeout,
CURLOPT_HEADER => false,
CURLOPT_SSL_VERIFYPEER => true,
]);
$response = curl_exec($ch);
if (curl_errno($ch)) {
error_log("cURL GET Error: " . curl_error($ch));
curl_close($ch);
return null;
}
curl_close($ch);
return $response;
}
curl_init()curl_setopt() / curl_setopt_array()curl_exec()curl_errno() / curl_error()curl_close()curl_multi 實現並發,大幅降低串行請求總耗時。; php.ini
extension=curl
; 確保以下 DLL 存在於 PHP 目錄或系統 PATH:
; libssh2.dll, libeay32.dll, ssleay32.dll (PHP 7.2 前)
; libssl-*.dll, libcrypto-*.dll (PHP 7.2+ OpenSSL 1.1)
; libssh2.dll (SFTP 支援)
重啟 Apache / Nginx / PHP-FPM。
yum install php-curl -y
systemctl restart php-fpm
apt-get update && apt-get install php-curl -y
systemctl restart php-fpm
# Dockerfile
FROM php:8.2-fpm
RUN apt-get update && apt-get install -y libcurl4-openssl-dev \
&& docker-php-ext-install curl
php -m | grep curl
# 或
php -r "var_dump(curl_version());"
| 現象 | 原因 | 解決 |
|---|---|---|
| SSL certificate problem | CA 憑證缺失或過期 | 更新 ca-bundle.crt 或設定 CURLOPT_CAINFO |
| Connection timed out | 防火牆/安全組阻擋、DNS 失敗 | 檢查網路連通性、調整 Timeout |
| Empty reply from server | 對方關閉連線、協議不匹配 | 檢查 HTTP/HTTPS、HTTP/2 設定 |
| Memory exhausted | 大檔案未用串流 | 使用 CURLOPT_WRITEFUNCTION 寫入檔案 |
| Protocol "https" not supported | 編譯時未啟用 OpenSSL | 重新編譯或安裝正確套件 |
// 發起多個請求,輪詢完成狀態
$mh = curl_multi_init();
$chs = [];
foreach ($urls as $i => $url) {
$chs[$i] = curl_init($url);
curl_setopt($chs[$i], CURLOPT_RETURNTRANSFER, true);
curl_multi_add_handle($mh, $chs[$i]);
}
$active = null;
do {
$mrc = curl_multi_exec($mh, $active);
if ($mrc != CURLM_OK) { break; }
// 此處可做其他工作 (非阻塞)
curl_multi_select($mh, 0.1); // 等待 100ms
} while ($active);
$results = [];
foreach ($chs as $i => $ch) {
$results[$i] = curl_multi_getcontent($ch);
curl_multi_remove_handle($mh, $ch);
}
curl_multi_close($mh);
cURL 封裝成服務類、配合依賴注入容器管理生命週期,是現代 PHP 專案的標準做法。重點記住:永遠啟用 SSL 驗證、設定合理超時、使用 curl_multi 做並發、大檔案用串流處理。安裝問題多半是缺少 OpenSSL 開發庫或 DLL 路徑問題,依照作業系統標準安裝流程即可解決。