Go标准库无FTP客户端支持，需用github.com/jlaffaye/ftp；其自动处理PASV模式、MLSD解析与UTF-8协商，但上传下载必须显式Close()以确保传输完成，且中文路径需OPTS UTF8 ON启用。
Go 标准库不提供 FTP 客户端支持，net/ftp 不存在 —— 这是开发者踩坑的第一步。必须依赖第三方库，而当前最稳定、维护活跃、API 清晰的是 github.com/jlaffaye/ftp。
为什么不能用标准库的 net 包直接连 FTP
FTP 协议本身有控制连接（命令通道）和数据连接（传输通道）两路，且数据连接模式（主动/被动）需协商，还涉及 PORT/PASV 命令解析、端口动态分配、防火墙兼容等细节。标准库的 net 只提供底层 TCP/UDP 能力，没封装任何 FTP 状态机或命令序列逻辑。
常见错误现象：read tcp: i/o timeout 或 500 Illegal PORT command，基本都源于手动拼接 FTP 命令时忽略状态同步或 PASV 解析失败。
- 不要尝试用
net.Dial+ 手写USER/PASS序列 —— 控制流、编码（如空格转义）、响应码判断、多行响应处理全得自己实现 -
github.com/jlaffaye/ftp内置了完整的 RFC 959 兼容实现，自动处理 PASV 模式切换、MLSD 列表解析、UTF-8 文件名协商（需显式启用） - 该库默认使用被动模式（PASV），对 NAT/客户端防火墙友好；如需主动模式，需调用
Conn.ActiveMode()并确保客户端开放高位端口
如何安全登录并列出远程目录（含中文路径）
FTP 登录本身不加密，密码明文传输。若服务端未启用 FTPS（即 FTP over TLS），敏感环境应避免生产使用；但开发调试或内网场景下，可先聚焦功能实现。
立即学习“go语言免费学习笔记（深入）”；
关键点在于字符编码：RFC 2640 规定 FTP 默认使用 ISO-8859-1，但现代服务器（如 vsftpd、Pure-FTPd）常默认启用 UTF-8 扩展。不匹配会导致中文文件名乱码或 550 错误。
- 登录后立即调用
conn.EnterTLS()（需服务端支持 FTPS）或跳过 —— 但注意：该方法仅在建立连接后、认证前调用才有效 - 启用 UTF-8 支持：发送
OPTS UTF8 ON命令，再调用conn.SetTimeout()避免后续 LIST 超时 - 使用
conn.List()而非conn.Retr()+ 手动解析 LIST 响应 —— 前者已内置 MLSD / LIST 双模式自动降级，并正确解析权限、时间、大小字段 - 示例片段：
conn, err := ftp.Dial("ftp.example.com:21", ftp.DialWithTimeout(5*time.Second)) if err != nil { /* handle */ } defer conn.Quit()if err = conn.Login("user", "pass"); err != nil { / handle / }
// 启用 UTF-8（若服务端支持） _ = conn.Cmd("OPTS UTF8 ON", nil)
entries, err := conn.List("/中文目录") if err != nil { / handle / } for _, e := range entries { fmt.Printf("%s %s\n", e.Name, e.Time) // Name 已解码为 Go 字符串 }
上传与下载文件时的常见陷阱
Retr()和Stor()接口返回的是io.ReadCloser/io.WriteCloser，但它们**不阻塞等待传输完成** —— 必须显式调用Close()才会触发底层数据连接关闭及服务端响应确认（如226 Transfer complete）。漏掉Close()会导致文件截断、连接堆积、后续命令卡死。- 上传大文件时，避免一次性
io.Copy(conn.Stor(...), file)—— 应包装为带缓冲的bufio.Writer，并设置超时：conn.SetDeadline(time.Now().Add(30*time.Minute)) - 下载时若需校验完整性，应在
io.Copy后立即conn.Close()，再检查返回的 error；err == nil才代表服务端确认接收成功 - 遇到
425 Can't open data connection：大概率是 PASV 返回的 IP 被客户端网络策略拦截（如 Docker 容器内访问宿主机 FTP），此时需强制 ActiveMode 并配置客户端端口范围：conn.SetActiveMode(true); conn.SetDataPortRange(50000, 50100)
FTP 协议本身的无状态性、双连接模型、编码模糊性，决定了它比 HTTP 更容易在边界场景出问题。真正难的不是“怎么传”，而是“怎么知道传完了”和“怎么让不同服务器都认得同一个文件名”。
jlaffaye/ftp封装了大部分，但 PASV IP 解析逻辑、MLSD 时间格式兼容、断点续传（REST 命令）仍需你根据目标服务器行为微调。 - 上传大文件时，避免一次性
