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++ Code Review Master
下载
组合式C++代码评审方案，融合静态分析、AI推理、多轮迭代评审和C++专项检查，适用于PR审查、增量代码审查、全项目评审和代码质量评分，触发词包括review cpp、cpp代码评审、C++review、代码审查。
立即学习“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 会静默失败。
