錯誤現象
Fatal error: Uncaught Error: Call to undefined function curl_init() in ...
原因:PHP 未載入 `php_curl` 擴展。默認安裝通常**不啟用**。
解決步驟 (Windows / Linux / macOS 通用邏輯)
1. 定位 `php.ini`
- CLI: `php --ini` → `Loaded Configuration File`
- Web (Apache/Nginx+FPM): 創建 `` 訪問,查找 `Loaded Configuration File`。
- 常見路徑:
- Windows: `C:\php\php.ini` 或 Apache `bin\php.ini`
- Linux: `/etc/php/8.2/cli/php.ini` (CLI)、`/etc/php/8.2/fpm/php.ini` (FPM)
- macOS (Homebrew): `/opt/homebrew/etc/php/8.2/php.ini`
2. 編輯 `php.ini`,啟用擴展
搜索 `extension=curl`,取消註釋 (刪除前面的 `;`):
; 修改前
;extension=curl
; 修改後
extension=curl
注意: PHP 7.2+ **不再需要**寫 `.dll`/`.so` 後綴,僅寫 `extension=curl` 即可 (跨平台通用)。舊版本 Windows 需 `extension=php_curl.dll`,Linux 需 `extension=curl.so`。
3. 確認擴展文件存在
- Windows: `ext\php_curl.dll` (PHP 目錄下 `ext` 文件夾)。
- Linux: `curl.so` 通常由包管理器安裝在擴展目錄 (`extension_dir`)。
若文件缺失:
- Windows: 下載對應 PHP 版本/架構 (TS/NTS) 的 zip 包提取 `ext/php_curl.dll`。
- Linux: `apt install php8.2-curl` / `yum install php-curl` / `apk add php82-curl`。
- macOS: `brew install php@8.2` (通常含 curl) 或 `pecl install curl` (罕見)。
4. 重啟 PHP 進程 / Web 服務器
- PHP-FPM: `systemctl restart php8.2-fpm` / `service php-fpm restart` / `brew services restart php`
- Apache (mod_php): `systemctl restart apache2` / `httpd -k restart`
- Nginx + FPM: 重啟 FPM 即可,Nginx 無需重啟。
- CLI: 無需重啟,下次運行生效。
5. 驗證是否生效
<?php
// CLI
php -m | grep curl
# 或
php -r "var_dump(function_exists('curl_init'));"
// Web: 訪問 phpinfo() 頁面,搜索 "curl support" → enabled
?>
測試代碼
<?php
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => 'https://httpbin.org/get',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HEADER => false,
CURLOPT_TIMEOUT => 10,
CURLOPT_SSL_VERIFYPEER => true, // 生產環境必須 true
]);
$response = curl_exec($ch);
if ($response === false) {
echo 'cURL Error: ' . curl_error($ch);
} else {
echo 'Success! Response length: ' . strlen($response);
}
curl_close($ch);
?>
常見坑點
- 修改錯誤的 php.ini:CLI 與 FPM/Apache 可能用不同 ini,**必須修改 Web 運行環境對應的 ini**。
- 忘記重啟服務:修改 ini 後必須重啟對應進程。
- Windows 依賴 DLL:`libssh2.dll`、`libcrypto-*.dll`、`libssl-*.dll` 需在 PATH 中 (通常放 PHP 目錄並加入系統 PATH)。
- SELinux (Linux):可能阻止 HTTPD 讀取擴展文件,檢查 `audit.log`,或 `setsebool -P httpd_can_network_connect 1` (允許網絡連接)。
- OpenSSL 版本不匹配:cURL 依賴 OpenSSL,版本衝突會導致啟動失敗或 SSL 錯誤。
Docker 環境
# Dockerfile
FROM php:8.2-fpm
RUN apt-get update && apt-get install -y libcurl4-openssl-dev \
&& docker-php-ext-install curl
# 或使用官方擴展安裝腳本
# RUN docker-php-ext-install curl