C++如何调用SFTP上传下载文件？（libssh2集成示例）

libssh2_error_kex_failure（-37）主因是密钥交换算法不匹配；openssh 9.0+禁用diffie-hellman-group1-sha1，而旧版libssh2默认依赖该算法，导致协商失败。

libssh2_session_handshake失败：证书或加密套件不匹配

调用 libssh2_session_handshake() 返回 -37（LIBSSH2_ERROR_KEX_FAILURE）很常见，根本原因不是密码错，而是客户端和SFTP服务器支持的密钥交换算法、加密方式不重叠。OpenSSH 9.0+ 默认禁用 diffie-hellman-group1-sha1，而老版本 libssh2（

• 强制指定兼容套件：在 libssh2_session_init_ex() 后、handshake 前调用 libssh2_session_set_blocking(session, 1)，再用 libssh2_session_method_pref(session, LIBSSH2_METHOD_KEX, "ecdh-sha2-nistp256,diffie-hellman-group14-sha1")
• 检查服务器支持的算法：用命令 ssh -Q kex user@host 或抓包看 server_kexinit
• 避免静态链接旧版 OpenSSL：libssh2 编译时若绑定 OpenSSL 1.0.x，可能无法协商 TLS 1.2+ 的曲线参数

sftp_open返回NULL：路径、权限或SFTP子系统未启用

libssh2_sftp_open() 返回 NULL 不一定代表连接断了，更可能是服务端拒绝访问——尤其是路径含中文、开头带 ~、或目标目录不可写。

• 绝对路径优先：不要传 "~/data/file.txt"，先用 libssh2_channel_exec() 调 pwd 拿到 home，再拼接 "/home/user/data/file.txt"
• SFTP 子系统必须启用：确认服务器 /etc/ssh/sshd_config 有 Subsystem sftp /usr/lib/openssh/sftp-server 或 internal-sftp，且对应用户 shell 未被设为 /bin/false（除非配置了 ForceCommand internal-sftp）
• 中文路径需 UTF-8 编码：确保你的 c++ 字符串是 UTF-8（非本地 locale），libssh2 内部不转码

上传卡在libssh2_sftp_write：缓冲区与阻塞模式没配对

调用 libssh2_sftp_write() 返回值小于预期字节数，甚至一直返回 0，通常是因为 session 阻塞模式和底层 socket 设置冲突，或 SFTP 通道缓存溢出。

• 必须同步设置阻塞模式：调用 libssh2_session_set_blocking(session, 1) 后，socket 也得是阻塞的（fcntl(fd, F_SETFL, 0)）；若用非阻塞 socket，则 session 必须设为非阻塞（libssh2_session_set_blocking(session, 0)），并循环检查 LIBSSH2_ERROR_EAGAIN
• 单次写入别超 32KB：libssh2 内部 SFTP packet 有默认上限，大文件分块传，每块 ≤32768 字节
• 别漏掉 libssh2_sftp_close()：不关句柄会导致后续 libssh2_sftp_shutdown() 失败，下次连接 handshake 可能卡住

下载时libssh2_sftp_read读不到完整数据：EOF判断不准

libssh2_sftp_read() 在接近文件尾时容易提前返回 0，误判为 EOF，尤其当服务器是 ProFTPD 或某些嵌入式 SFTP 实现时。

立即学习“C++免费学习笔记（深入）”；

• 不能只靠返回值 0 判定结束：要结合 libssh2_sftp_stat() 获取文件大小，用已读字节数对比判断是否真结束
• 每次读前检查 channel 状态：在循环内加 if (libssh2_session_last_error(session, nullptr, nullptr, 0) == LIBSSH2_ERROR_EAGAIN) continue;
• 小文件建议一次性读完：用 libssh2_sftp_fstat() 拿 size，malloc 对应 buffer，再 libssh2_sftp_read() 循环直到读满（而非直到返回 0）

libssh2 对 SFTP 协议的实现偏底层，没有自动重试、断点续传或路径 glob 支持——这些都得你自己补。最易忽略的是：每次 libssh2_sftp_open() 成功后，必须用对应的 libssh2_sftp_handle 调 libssh2_sftp_read()/libssh2_sftp_write()，混用 session 或不同 handle 会静默失败。