PHP FTP 函數完整教程：連線、上傳下載、目錄操作與非阻塞傳輸

FTP 擴展簡介

PHP FTP 擴展提供完整的 FTP 客戶端功能：連線認證、檔案上傳下載、目錄操作、權限修改、非阻塞傳輸、SSL/TLS 加密連線。Windows 版 PHP 內建，Linux 需編譯時加入 --enable-ftp。

安裝驗證

# Linux 編譯參數
./configure --enable-ftp

# 驗證
php -m | grep ftp
php -r "var_dump(function_exists('ftp_connect'));"

核心函數分類速查

連線與認證

目錄操作

檔案操作

傳輸模式常數

• FTP_ASCII / FTP_TEXT：文本模式（換行轉換）
• FTP_BINARY / FTP_IMAGE：二進制模式（圖片、壓縮檔、執行檔必須用此模式）

非阻塞傳輸（大檔案/斷點續傳核心）

實戰範例

1. 基礎上傳下載封裝類

<?php
class FtpClient {
  private $conn;
  private $config;

  public function __construct(array $config) {
    $this->config = $config;
  }

  public function connect() {
    $this->conn = $this->config['ssl'] 
      ? @ftp_ssl_connect($this->config['host'], $this->config['port'] ?? 990, 30)
      : @ftp_connect($this->config['host'], $this->config['port'] ?? 21, 30);
    
    if (!$this->conn) throw new Exception("連線失敗: {$this->config['host']}");
    
    if (!@ftp_login($this->conn, $this->config['user'], $this->config['pass'])) {
      throw new Exception("認證失敗");
    }
    
    ftp_pasv($this->conn, true); // 被動模式
    return $this;
  }

  public function upload($localPath, $remotePath, $mode = FTP_BINARY) {
    return ftp_put($this->conn, $remotePath, $localPath, $mode);
  }

  public function download($remotePath, $localPath, $mode = FTP_BINARY) {
    return ftp_get($this->conn, $localPath, $remotePath, $mode);
  }

  public function delete($remotePath) {
    return ftp_delete($this->conn, $remotePath);
  }

  public function listFiles($dir = '.') {
    return ftp_nlist($this->conn, $dir);
  }

  public function __destruct() {
    if ($this->conn) @ftp_close($this->conn);
  }
}

// 使用
$ftp = new FtpClient([
  'host' => 'ftp.example.com',
  'user' => 'username',
  'pass' => 'password',
  'ssl'  => true, // FTPS
]);
$ftp->connect()->upload('local.jpg', '/remote/images/photo.jpg');
$ftp->download('/remote/backup.sql', 'backup.sql');

2. 非阻塞大檔案下載（含進度條邏輯）

<?php
function downloadLarge($ftp, $remote, $local) {
  $fp = fopen($local, 'w');
  $ret = ftp_nb_fget($ftp, $fp, $remote, FTP_BINARY, 0); // 0 = 從頭開始
  
  $total = ftp_size($ftp, $remote);
  $downloaded = 0;
  
  while ($ret === FTP_MOREDATA) {
    // 這裡可以更新進度條、寫入日誌、處理其他任務
    $downloaded = ftell($fp);
    echo "\r進度: " . round($downloaded/$total*100, 1) . "%";
    $ret = ftp_nb_continue($ftp);
  }
  
  fclose($fp);
  
  if ($ret !== FTP_FINISHED) {
    unlink($local); // 失敗刪除不完整檔案
    throw new Exception("下載失敗");
  }
  echo "\n下載完成\n";
}

3. 斷點續傳上傳

<?php
function uploadResume($ftp, $local, $remote) {
  $localSize = filesize($local);
  $remoteSize = ftp_size($ftp, $remote);
  
  if ($remoteSize >= $localSize) return true; // 已完成
  
  $fp = fopen($local, 'r');
  fseek($fp, $remoteSize); // 跳過已上傳部分
  
  $ret = ftp_nb_fput($ftp, $remote, $fp, FTP_BINARY, $remoteSize);
  
  while ($ret === FTP_MOREDATA) {
    $ret = ftp_nb_continue($ftp);
  }
  
  fclose($fp);
  return $ret === FTP_FINISHED;
}

常見問題與最佳實踐

安全建議

1. 優先使用 ftp_ssl_connect (FTPS) 或 SFTP (需 ssh2 擴展或 phpseclib)
2. 避免在代碼中硬編碼密碼，使用環境變數或密碼管理器
3. 限制 FTP 用戶權限：僅開放必要目錄，禁止 Shell 登入
4. 記錄所有 FTP 操作日誌（IP、用戶、操作、檔案、結果）