萬盛學電腦網

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

PHP cURL 實現 FTP 檔案下載:解決 ftp_get 速度慢、大檔案超時問題

原生 ftp_get() 下載大檔案常遭遇速度極慢、逾時中斷。改用 cURL 的 FTP 協定支援,可獲得穩定、高速的下載效能,並支援斷點續傳擴展。本文提供封裝良好的下載函數與關鍵參數說明。

封裝函數:curl_ftp_download()

<?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_URLftp://ip/pathFTP URL 格式,含認證資訊時可寫 ftp://user:pass@ip/path
CURLOPT_FILEfopen($path, 'w+')直接串流寫入檔案,**避免大檔案佔用 PHP 記憶體**
CURLOPT_FTPPORT'' (空字串)**關鍵**:強制使用被動模式 (PASV),解決防火牆/NAT 導致的資料連線失敗
CURLOPT_FTP_USE_EPSVfalse關閉延伸被動模式 (EPSV),提升相容性
CURLOPT_TIMEOUT2000總作業逾時,**大檔案必須設大**,單位秒
CURLOPT_LOW_SPEED_LIMIT1024低速限制 (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; // 已完整

常見問題排查

  • 連線逾時:檢查防火牆是否開放 TCP 21 (命令) + 被動模式埠範圍 (需在 FTP 伺服器設定固定範圍並開放)。
  • 權限不足:FTP 用戶需對遠端檔案有讀取權限,本地目錄需 PHP 進程寫入權限。
  • 二進位/ASCII 模式:cURL FTP 預設二進位,無需切換;舊版 ftp_get 需指定 FTP_BINARY。
  • SFTP ≠ FTP:若伺服器為 SFTP (SSH File Transfer Protocol),需改用 ssh2_scp_recv 或 phpseclib,cURL 7.16.4+ 支援 sftp:// 但需編譯 libssh2 支援。

採用 cURL + 被動模式 + 檔案串流寫入,可穩定解決 PHP FTP 大檔案下載的速度與逾時難題。

copyright © 萬盛學電腦網 all rights reserved