ftplib不解析ftp://前缀，需用urllib.parse.urlparse提取hostname和port后调用connect()；连接成功但dir()/nlst()超时多因PASV响应含不可达内网IP，应检查服务器ForcePassiveIP配置或尝试set_pasv(False)。
ftplib.connect() 传入 ftp:// 开头的 URL 报错
直接把 ftp://192.168.5.123 当作主机名传给 ftplib.FTP() 或 connect()，会触发 gaierror 或连接拒绝——因为 ftplib 不解析 URL 协议头，只认纯主机名或 IP。
- 用
urllib.parse.urlparse()提取hostname、port（默认 21）、path -
FTP()实例化后调用connect(host=..., port=...)，别塞进构造函数 - 如果 URL 含用户信息（如
ftp://user:pass@host/...），记得额外调用login()，不要依赖 URL 自动鉴权
连接成功但 dir()/nlst() 超时（WinError 10060）
常见于服务器启用了被动模式（PASV），但返回的 PASV 响应中包含内网 IP（如 227 Entering Passive Mode (10,19,1,137,195,128)），客户端无法路由到该地址，导致数据通道建立失败。
- 启用被动模式：调用
ftp.set_pasv(True)（默认就是 True，但显式设更稳妥） - 若服务器 NAT 配置错误，可尝试强制使用主动模式：
ftp.set_pasv(False)（需确保客户端防火墙放行高位端口入站） - 部分 FTP 服务（如 Pure-FTPd）需在服务端配置
ForcePassiveIP指向公网 IP，否则客户端永远连不上数据端口
登录后操作报 [WinError 10054] 连接被重置
这不是网络断开，而是服务器主动终止了控制连接。典型原因是服务器设置了“空闲超时”，而你的代码在 login() 后未及时发起命令（比如卡在输入路径、等待用户交互），或执行 retrbinary() 前间隔太久。
- 检查服务器配置：FileZilla Server 的「Idle timeout」、vsftpd 的
idle_session_timeout、Pure-FTPd 的-A参数 - 在关键操作前加
ftp.voidcmd("NOOP")保活（注意不是所有服务器支持 NOOP） - 避免长耗时本地处理；下载大文件时，用回调函数分块处理，别让控制连接挂起
中文文件名乱码或 listdir 报 UnicodeDecodeError
FTP 协议本身不携带编码信息，nlst() 返回的是原始字节串（bytes），直接 decode 可能失败，尤其当服务器用 GBK 而客户端按 UTF-8 解。
立即学习“Python免费学习笔记（深入）”；
- 别对
nlst()结果直接.decode('utf-8')；改用兼容解码函数，按顺序尝试['utf-8', 'gbk', 'latin-1'] - 下载文件时，
retrbinary()的回调接收的是原始 bytes，文件名和内容编码要分开处理 - 某些 FTP 服务（如 vsftpd）可通过配置
utf8_filesystem=YES统一用 UTF-8，但需服务端支持且重启生效
ftp.set_debuglevel(2) 看完整交互日志，比盲目调参数更有效。 
