PHP FTP 連線與檔案上傳完整實作指南

前言

PHP 內建 FTP 擴充功能提供完整的 FTP 客戶端操作能力，適用於自動化部署、檔案同步、備份系統等場景。本文系統整理核心函式並提供完整可執行範例。

核心 FTP 函式速查表

傳輸模式常數

• FTP_ASCII：文字檔（自動轉換換行符）
• FTP_BINARY：二進位檔（圖片、壓縮檔、執行檔等，預設建議）

完整上傳範例（含錯誤處理）

<?php
/**
 * FTP 檔案上傳封裝函式
 * 
 * @param array $config 連線設定
 * @param string $localPath 本地檔案路徑
 * @param string $remotePath 遠端儲存路徑（含檔名）
 * @param int $mode 傳輸模式 FTP_BINARY|FTP_ASCII
 * @return bool|string 成功回傳 true，失敗回傳錯誤訊息
 */
function ftpUpload(array $config, $localPath, $remotePath, $mode = FTP_BINARY) {
    // 1. 檢查本地檔案
    if (!file_exists($localPath) || !is_file($localPath)) {
        return "本地檔案不存在: {$localPath}";
    }
    if (!is_readable($localPath)) {
        return "本地檔案不可讀: {$localPath}";
    }

    // 2. 建立連線
    $conn = @ftp_connect($config['host'], $config['port'] ?? 21, $config['timeout'] ?? 30);
    if (!$conn) {
        return "無法連線至 FTP 伺服器: {$config['host']}";
    }

    // 3. 登入驗證
    $login = @ftp_login($conn, $config['username'], $config['password']);
    if (!$login) {
        ftp_close($conn);
        return "FTP 登入失敗，請檢查帳號密碼";
    }

    // 4. 設定被動模式（推薦）
    if (isset($config['pasv']) && $config['pasv']) {
        ftp_pasv($conn, true);
    }

    // 5. 確保遠端目錄存在
    $remoteDir = dirname($remotePath);
    if ($remoteDir !== '.' && $remoteDir !== '/') {
        // 遞迴建立目錄（簡易版）
        $dirs = explode('/', trim($remoteDir, '/'));
        $currentPath = '';
        foreach ($dirs as $dir) {
            $currentPath .= '/' . $dir;
            @ftp_chdir($conn, $currentPath) || @ftp_mkdir($conn, $currentPath);
        }
    }

    // 6. 執行上傳
    $result = ftp_put($conn, $remotePath, $localPath, $mode);
    
    // 7. 關閉連線
    ftp_close($conn);

    return $result ? true : "檔案上傳失敗（權限不足或磁碟空間不足）";
}

// 使用範例
$ftpConfig = [
    'host' => 'ftp.example.com',
    'port' => 21,
    'username' => 'user123',
    'password' => 'secret456',
    'timeout' => 30,
    'pasv' => true  // 建議開啟被動模式
];

$uploadResult = ftpUpload($ftpConfig, '/var/www/uploads/report.pdf', '/backups/report_2024.pdf');

if ($uploadResult === true) {
    echo "✅ 上傳成功！\n";
} else {
    echo "❌ 上傳失敗: {$uploadResult}\n";
}
?>

常見問題與解決方案

進階應用建議

1. 斷點續傳： 使用 ftp_fput() 搭配檔案指標 fseek() 實現
2. SSL/TLS 加密： 改用 ftp_ssl_connect()（需 PHP 編譯支援 OpenSSL）
3. 批量同步： 結合 ftp_nlist() 遞迴比對本地/遠端檔案清單
4. 非同步處理： 將 FTP 操作放入佇列（Redis/RabbitMQ）由 Worker 處理

PHP FTP 函式雖然基礎，但配合妥善的錯誤處理、被動模式與目錄管理，足以應付大多數自動化檔案傳輸需求。