Golang实现FTP/SFTP文件传输教程

本文深入解析了在Go语言中实现FTP和SFTP文件传输的关键实践与常见陷阱：由于Go标准库不提供原生支持，必须依赖第三方库（jlaffaye/ftp用于FTP、pkg/sftp用于SFTP），但二者API迥异、不可混用；FTP需强制启用被动模式、严格使用正斜杠路径、上传后务必关闭WriteCloser，而SFTP则需先建立SSH连接再创建客户端，认证支持密码或私钥（后者需正确解析PEM密钥），且文件操作不保证原子性；更关键的是，错误处理不能仅依赖err != nil——FTP需检查响应码（如550），SFTP应使用errors.Is进行语义化判断（如os.ErrNotExist），避免字符串匹配带来的跨平台风险；路径分隔符、超时设置、连接复用等细节，往往才是实际开发中耗时最长的“隐形地雷”。

Go 里没有内置 FTP/SFTP 支持，得靠第三方库

标准库 net/ftp 不存在，crypto/ssh 也不直接提供 SFTP 客户端。想传文件，必须引入外部包。别试图自己拼接 FTP 命令或手写 SSH 协议——协议细节多、边界情况杂，出错难调试。

主流选择就两个：github.com/jlaffaye/ftp（纯 FTP）和 github.com/pkg/sftp（基于 golang.org/x/crypto/ssh 的 SFTP 客户端）。两者 API 风格差异大，不能混用，选错库会导致连接成功但 Open 或 WriteTo 报奇怪错误。

用 github.com/jlaffaye/ftp 传文件：注意被动模式和路径斜杠

FTP 客户端默认主动模式（PORT），但在 Docker、NAT 后或云主机上基本连不上。必须显式启用被动模式：

conn, err := ftp.Dial("ftp.example.com:21", ftp.DialWithTimeout(5*time.Second))
if err != nil {
    log.Fatal(err)
}
err = conn.Login("user", "pass")
if err != nil {
    log.Fatal(err)
}
// 关键：启用被动模式
conn.EnterPassiveMode()

• EnterPassiveMode() 必须在 Login() 之后、任何文件操作之前调用
• 远程路径必须用 /（Unix 风格），即使目标是 Windows FTP 服务器；用 \ 会静默失败或报 550 File not found
• 上传大文件时，conn.Stor() 返回的 io.WriteCloser 必须显式 Close()，否则文件可能截断且无错误提示

用 github.com/pkg/sftp 传文件：SSH 认证方式决定代码结构

SFTP 是 SSH 子系统，先建 SSH 连接，再开 SFTP 会话。认证方式直接影响初始化逻辑：

• 密码登录：用 ssh.ClientConfig{User: ..., Auth: []ssh.AuthMethod{ssh.Password("xxx")}}
• 私钥登录：必须加载 PEM 格式密钥，ssh.Signer 不能直接读 *os.File，要先 ioutil.ReadFile 再 ssh.ParsePrivateKey
• 连接后必须调用 sftp.NewClient(conn)，不是 conn.NewSFTP()（后者是旧版 API，已废弃）

常见坑：client.Create() 返回的 *sftp.File 不支持 WriteAt，且 Write() 不保证原子性；若需断点续传，得用 client.OpenFile(..., os.O_WRONLY|os.O_APPEND) 并自行处理偏移。

FTP 和 SFTP 错误处理不能只看 err != nil

FTP 库很多错误不返回 error，而是通过 ftp.Response 状态码体现，比如 conn.Retr() 成功返回 io.ReadCloser，但后续读取时可能遇到 550 Permission denied —— 这个错误直到 Read() 才暴露。

SFTP 更隐蔽：client.Stat() 对不存在路径返回 *os.PathError，但它的 Err 字段是 syscall.Errno(2)（即 ENOENT），不是字符串匹配；直接 strings.Contains(err.Error(), "no such") 在不同系统上可能失效。

真正可靠的判断方式是类型断言：if errors.Is(err, os.ErrNotExist)（SFTP）或检查 resp.Code 是否为 550（FTP）。

路径分隔符、超时控制、连接复用这些细节，往往比选库本身更耗调试时间。

今天关于《Golang实现FTP/SFTP文件传输教程》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！