C# 實作 FTP 上傳與下載完整教學：原理、代碼與最佳實踐

前言

在企業級應用開發中，檔案傳輸是常見需求。FTP (File Transfer Protocol) 因其通用性與成熟度，仍是許多系統整合的首選。本文將深入淺出地說明如何在 C# 中使用 FtpWebRequest 實作檔案上傳與下載，並提供可直接部署的完整代碼範例。

核心類別：FtpWebRequest

System.Net.FtpWebRequest 是 .NET Framework 內建的 FTP 客戶端實作，支援上傳、下載、刪除、列表目錄等操作。它繼承自 WebRequest，採用請求/回應模式，適合同步阻塞式程式設計。

上傳檔案完整實作

public static void UploadFile(string localFilePath, string ftpServerUri, string username, string password)
{
    FileInfo fileInfo = new FileInfo(localFilePath);
    // 建立請求 URI，包含伺服器位址與檔名
    FtpWebRequest request = (FtpWebRequest)WebRequest.Create(new Uri(ftpServerUri + fileInfo.Name));
    request.Credentials = new NetworkCredential(username, password);
    request.Method = WebRequestMethods.Ftp.UploadFile;
    request.UseBinary = true;          // 二進位模式，避免文字檔換行符轉換
    request.KeepAlive = false;         // 關閉長連線，適合單次操作
    request.ContentLength = fileInfo.Length;

    const int BufferSize = 20480;
    byte[] buffer = new byte[BufferSize];
    int bytesRead;

    try
    {
        using (FileStream fs = fileInfo.OpenRead())
        using (Stream requestStream = request.GetRequestStream())
        {
            while ((bytesRead = fs.Read(buffer, 0, BufferSize)) > 0)
            {
                requestStream.Write(buffer, 0, bytesRead);
            }
        }
        // 取得回應以確認伺服器狀態碼
        using (FtpWebResponse response = (FtpWebResponse)request.GetResponse())
        {
            Console.WriteLine($"上傳完成，狀態: {response.StatusDescription}");
        }
    }
    catch (WebException ex)
    {
        Console.WriteLine($"上傳失敗: {ex.Message}");
        if (ex.Response is FtpWebResponse ftpResp)
            Console.WriteLine($"伺服器回應: {ftpResp.StatusDescription}");
    }
}

下載檔案完整實作

public static void DownloadFile(string remoteFileName, string ftpServerUri, string username, string password, string localSavePath)
{
    FtpWebRequest request = (FtpWebRequest)WebRequest.Create(new Uri(ftpServerUri + remoteFileName));
    request.Credentials = new NetworkCredential(username, password);
    request.Method = WebRequestMethods.Ftp.DownloadFile;
    request.UseBinary = true;

    try
    {
        using (FtpWebResponse response = (FtpWebResponse)request.GetResponse())
        using (Stream responseStream = response.GetResponseStream())
        using (FileStream fs = new FileStream(localSavePath, FileMode.Create, FileAccess.Write))
        {
            byte[] buffer = new byte[20480];
            int bytesRead;
            while ((bytesRead = responseStream.Read(buffer, 0, buffer.Length)) > 0)
            {
                fs.Write(buffer, 0, bytesRead);
            }
        }
        Console.WriteLine("下載完成");
    }
    catch (WebException ex)
    {
        Console.WriteLine($"下載失敗: {ex.Message}");
    }
}

關鍵參數與最佳實踐

• UseBinary：預設為 true，傳輸圖片、壓縮檔、執行檔等二進位檔案時必須保持 true；純文字檔若需自動換行轉換可設為 false。
• KeepAlive：設為 false 可在每次操作後關閉連線，避免伺服器連線數耗盡；若需大量連續傳輸，可設為 true 並手動管理連線池。
• 啟用 SSL/TLS：生產環境建議設定 request.EnableSsl = true，並確認伺服器支援 FTPS。
• 被動模式：預設為被動模式 (PASV)，可穿透防火牆；若伺服器僅支援主動模式，設定 request.UsePassive = false。
• 例外處理：務必捕捉 WebException，並檢查 Response 物件以取得 FTP 狀態碼 (如 550 檔案不存在、530 登入失敗)。

進階主題：非同步與大檔案支援

.NET 4.5 起可搭配 async/await 使用 GetRequestStreamAsync、GetResponseAsync 避免阻塞 UI 執行緒。超大檔案 (超過 2GB) 需啟用 request.ContentLength = -1 並分塊上傳，或改用第三方函式庫 (如 FluentFTP) 取得更完整的斷點續傳、進度回報功能。

總結

FtpWebRequest 雖屬舊版 API，但在無法引入外部套件的環境中，仍是輕量、零依賴的最佳選擇。掌握其核心屬性與流程控制，即可快速建立穩健的檔案傳輸模組。