怎样通过Python的ftplib库实现FTP文件上传与下载

访客网络编程 2026-06-05 07:35:02 1

掌握Python ftplib：FTP文件上传与下载实战指南

目录导读

引言：为什么选择ftplib？
ftplib库核心模块解析
环境搭建与基础连接
文件上传全流程详解
文件下载关键技巧
异常处理与安全实践
常见问题问答（FAQ）

引言：为什么选择ftplib？

在企业级数据交换、网站备份、资源分发场景中，FTP协议仍是最稳定的文件传输方式之一，Python内置的ftplib库无需安装第三方依赖，提供最轻量级的FTP操作方案，相比paramiko（SFTP）或requests（HTTP上传），ftplib直接支持主动/被动模式切换，更适合处理大量文件的批量传输。

但很多开发者常遇到：中文文件名乱码、被动模式连接失败、大文件内存溢出、匿名登录权限错误等问题，本文将通过实战代码逐一拆解。

ftplib库核心模块解析

ftplib.FTP类提供了完整的方法体系：

connect(host, port)：连接FTP服务器（默认端口21）
login(user, passwd)：身份验证（匿名登录可用'anonymous'）
cwd(path)：切换工作目录
retrbinary(cmd, callback)：二进制模式下载文件
storbinary(cmd, file)：二进制模式上传文件
dir() / nlst()：列出文件列表
quit()：安全断开连接

关键概念：被动模式（PASV）需额外调用set_pasv(True)，现代服务器普遍要求此模式以避免防火墙拦截。

环境搭建与基础连接

from ftplib import FTP
# 连接服务器（示例使用测试服务器：ftp.dlptest.com）
ftp = FTP()
ftp.connect('ftp.dlptest.com', 21)  # 时长约1-3秒
ftp.login('dlpuser', 'rNrKYTX9g7z3RgJRmxWuGHbeu')  # 匿名登录可省略参数
# 检查连接状态
print(ftp.getwelcome())  # 输出：220 Welcome to the FTP service
# 列出根目录文件
ftp.dir()  # 或使用 ftp.nlst()
ftp.quit()

常见卡点：超时配置需显式设置ftp.connect(timeout=30)；中文编码可使用ftp.encoding = 'utf-8'。

文件上传全流程详解

1 基础上传（小文件）

def upload_file(local_path, remote_path):
    with open(local_path, 'rb') as f:
        ftp.storbinary(f'STOR {remote_path}', f)

2 带进度监听的上传

import os
from tqdm import tqdm  # 可选进度条库
def upload_with_progress(local_path, remote_path):
    file_size = os.path.getsize(local_path)
    with open(local_path, 'rb') as f, tqdm(total=file_size, unit='B') as pbar:
        def callback(chunk):
            pbar.update(len(chunk))
        ftp.storbinary(f'STOR {remote_path}', f, callback=callback)

3 解决中文文件名乱码

ftp.encoding = 'utf-8'  # 大多数Linux服务器使用UTF-8
# 若服务器是Windows，尝试 ftp.encoding = 'gbk'

4 断点续传

def upload_resume(local_path, remote_path):
    # 获取远程已有文件大小（需服务器支持REST指令）
    ftp.sendcmd(f'REST {os.path.getsize(local_path)}')
    with open(local_path, 'ab') as f:
        ftp.storbinary(f'STOR {remote_path}', f)

文件下载关键技巧

1 安全下载到本地

def download_file(remote_path, local_path):
    with open(local_path, 'wb') as f:
        ftp.retrbinary(f'RETR {remote_path}', f.write)

2 内存优化：流式处理大文件

def download_stream(remote_path):
    from io import BytesIO
    buffer = BytesIO()
    ftp.retrbinary(f'RETR {remote_path}', buffer.write)
    buffer.seek(0)
    return buffer  # 可直接用于pandas或图像处理

3 目录递归下载

def download_dir(remote_dir, local_dir):
    os.makedirs(local_dir, exist_ok=True)
    ftp.cwd(remote_dir)
    for item in ftp.nlst():
        if '.' in item:  # 简单判断文件（或调用mlsd()获取类型）
            local_file = os.path.join(local_dir, item)
            download_file(item, local_file)
        else:
            download_dir(item, os.path.join(local_dir, item))

异常处理与安全实践

1 完整异常捕获框架

from ftplib import error_perm, error_temp
try:
    ftp = FTP()
    ftp.connect('your-server.com', 21, timeout=30)
    ftp.login('user', 'password')
    ftp.set_pasv(True)
    # 执行传输...
except error_perm as e:
    print(f"权限错误：{e}")  # 常见：530 Login incorrect
except error_temp as e:
    print(f"临时错误：{e}")  # 421 Service not available
except Exception as e:
    print(f"网络异常：{e}")
finally:
    try:
        ftp.quit()
    except:
        pass