libssh2_session_handshake失败常见原因包括：socket未成功建立tcp连接或端口不可达；未设为非阻塞模式导致超时；openssl未初始化；远程openssh版本升级（如v8.8）引发密钥交换失败（libssh2_error_kex_failure）；或套接字无效、标语发送失败等协议层错误。
libssh2_session_handshake失败常见原因
连接SSH服务器前必须完成握手，libssh2_session_handshake返回LIBSSH2_ERROR_TIMEOUT或LIBSSH2_ERROR_SOCKET_SEND通常不是代码写错了，而是底层网络或认证前置条件没满足。
- 确保socket已设为非阻塞（
fcntl(fd, F_SETFL, O_NONBLOCK)），libssh2默认依赖非阻塞IO；阻塞socket会导致超时 - 调用
libssh2_session_handshake前，必须已用connect()成功建立TCP连接，且确认对方端口（通常是22）可达 - OpenSSL初始化未做：在调用任何libssh2函数前，需执行
OPENSSL_init_ssl(OPENSSL_INIT_SSL_DEFAULT, NULL)（OpenSSL 1.1.1+）或SSL_library_init()（旧版）
如何正确加载私钥并完成用户认证
使用libssh2_userauth_publickey_fromfile认证失败，90%是因为路径、密码或密钥格式不匹配，而不是API调用顺序问题。
- 私钥文件路径必须是绝对路径或确保当前工作目录正确——libssh2不解析
~或环境变量 - 如果私钥有密码，传入的
passphrase参数不能为NULL；若为空密码，需传""（空字符串），而非NULL - 仅支持PEM格式的RSA/ECDSA密钥；OpenSSH新默认的
sk-ecdsa-sha2-nistp256@openssh.com等硬件密钥不被支持 - 认证前务必检查
libssh2_session_last_error，很多失败实际发生在libssh2_userauth_publickey_fromfile内部，但返回值是0（成功），需靠错误码判断真实状态
SFTP上传文件的核心步骤与易错点
libssh2本身不提供SFTP高层封装，必须手动管理LIBSSH2_SFTP和LIBSSH2_SFTP_HANDLE，漏掉任意一环都会导致libssh2_sftp_open返回NULL或写入静默失败。
- 先用
libssh2_sftp_init获取SFTP会话句柄，失败则整个SFTP流程不可用——该函数不依赖认证结果，但依赖handshake已完成 -
libssh2_sftp_open的flags参数必须含LIBSSH2_FXF_WRITE | LIBSSH2_FXF_CREAT | LIBSSH2_FXF_TRUNC（覆盖写）或LIBSSH2_FXF_APPEND（追加），缺一不可；只传LIBSSH2_FXF_WRITE会导致打开失败 - 每次
libssh2_sftp_write后要检查返回值是否等于本次尝试写入的字节数，libssh2可能只写入部分数据（尤其大文件），需循环直到写完 - 务必调用
libssh2_sftp_close_handle释放句柄，否则后续libssh2_sftp_shutdown可能卡住或泄漏资源
传输中断时如何安全清理资源
网络抖动或远程断连会导致libssh2_sftp_write或libssh2_sftp_close_handle返回负值，此时直接libssh2_session_free会引发内存泄漏甚至崩溃。
- 所有libssh2对象都有明确的销毁顺序：先
libssh2_sftp_close_handle→ 再libssh2_sftp_shutdown→ 最后libssh2_session_free - 若
libssh2_sftp_open失败，不要调用libssh2_sftp_shutdown；只有libssh2_sftp_init成功后才可调用shutdown - 出错时用
libssh2_session_last_error获取具体错误码（如LIBSSH2_ERROR_SFTP_PROTOCOL），比仅看函数返回值更能定位问题根源
libssh2的错误处理是链式的，一次失败可能影响后续所有操作，但它的API不自动重置状态。你得自己记清楚每个句柄是否有效，而不是指望库帮你兜底。
C++免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 C++ 的入门与实战技巧！
