原生 ftp_get() 下載大檔案常遭遇速度極慢、逾時中斷。改用 cURL 的 FTP 協定支援,可獲得穩定、高速的下載效能,並支援斷點續傳擴展。本文提供封裝良好的下載函數與關鍵參數說明。
<?php
/**
* 透過 cURL 下載 FTP 檔案
* @param string $ftpIp FTP 伺服器 IP
* @param string $ftpUser 使用者名稱
* @param string $ftpPwd 密碼
* @param string $remotePath 遠端檔案相對路徑 (如 'test/1.jpg')
* @param string $localPath 本地儲存完整路徑
* @return bool 成功 true / 失敗 false
*/
function curl_ftp_download($ftpIp, $ftpUser, $ftpPwd, $remotePath, $localPath) {
$ch = curl_init();
$url = "ftp://{$ftpIp}/{$remotePath}";
curl_setopt_array($ch, [
CURLOPT_URL => $url,
CURLOPT_USERPWD => "{$ftpUser}:{$ftpPwd}",
CURLOPT_RETURNTRANSFER => false, // 直接寫入檔案,不回傳字串
CURLOPT_HEADER => false,
CURLOPT_TIMEOUT => 2000, // 總逾時秒數 (大檔案需設大)
CURLOPT_CONNECTTIMEOUT => 60, // 連線逾時
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_FILE => fopen($localPath, 'w+'), // 寫入檔案指標
// 若需被動模式 (預設主動模式常被防火牆阻擋)
CURLOPT_FTPPORT => '', // 空字串強制被動模式
CURLOPT_FTP_USE_EPSV => false, // 關閉 EPSV,相容舊防火牆
]);
$result = curl_exec($ch);
$errno = curl_errno($ch);
$error = curl_error($ch);
fclose($ch); // 這裡會自動關閉 CURLOPT_FILE 指標
if ($errno) {
error_log("cURL FTP Error [$errno]: $error");
@unlink($localPath); // 失敗刪除不完整檔案
return false;
}
return true;
}
// 使用範例
if (curl_ftp_download('192.168.3.1', 'user', 'pass', 'backup/db.sql.gz', '/var/www/downloads/db.sql.gz')) {
echo '下載成功';
} else {
echo '下載失敗,請檢查日誌';
}
| 選項 | 關鍵值 | 說明 |
|---|---|---|
CURLOPT_URL | ftp://ip/path | FTP URL 格式,含認證資訊時可寫 ftp://user:pass@ip/path |
CURLOPT_FILE | fopen($path, 'w+') | 直接串流寫入檔案,**避免大檔案佔用 PHP 記憶體** |
CURLOPT_FTPPORT | '' (空字串) | **關鍵**:強制使用被動模式 (PASV),解決防火牆/NAT 導致的資料連線失敗 |
CURLOPT_FTP_USE_EPSV | false | 關閉延伸被動模式 (EPSV),提升相容性 |
CURLOPT_TIMEOUT | 2000 | 總作業逾時,**大檔案必須設大**,單位秒 |
CURLOPT_LOW_SPEED_LIMIT | 1024 | 低速限制 (bytes/sec),配合 LOW_SPEED_TIME 自動斷開卡住連線 |
// 續傳需求:支援斷點續傳
$localSize = file_exists($localPath) ? filesize($localPath) : 0;
if ($localSize > 0) {
curl_setopt($ch, CURLOPT_RESUME_FROM, $localSize);
curl_setopt($ch, CURLOPT_FILE, fopen($localPath, 'ab')); // 附加模式
}
// 遠端檔案大小預檢
curl_setopt($ch, CURLOPT_NOBODY, true); // HEAD 請求
curl_exec($ch);
$remoteSize = curl_getinfo($ch, CURLINFO_CONTENT_LENGTH_DOWNLOAD);
if ($localSize >= $remoteSize) return true; // 已完整
ftp_get 需指定 FTP_BINARY。ssh2_scp_recv 或 phpseclib,cURL 7.16.4+ 支援 sftp:// 但需編譯 libssh2 支援。採用 cURL + 被動模式 + 檔案串流寫入,可穩定解決 PHP FTP 大檔案下載的速度與逾時難題。