简介：面向需要在Windows 64位平台使用SSH2协议实现安全文件传输、远程shell等功能的C/C++开发者，这份由Visual Studio 2017编译生成的libssh2库压缩包可直接集成到项目中，免去自行下载源码、配置CMake与OpenSSL依赖的繁琐步骤。包内共115个文件，其中包含109个头文件、3个lib静态库、2个dll动态库及1个cpp示例源文件；头文件提供完整的API声明，lib供链接阶段使用，两个dll为运行时依赖，示例源文件可快速演示基本调用流程，整个压缩包仅2.14MB，轻量且易于分发。目前已有1507人学习下载。资源以完整编译产物的形式直接提供，开发者只需将libssh2.lib与头文件路径添加至VS2017项目属性，并将两个dll放置到可执行文件目录，即可完成SSH2安全连接；同时内附的OpenSSL 1.1系列dll能够规避因依赖版本不一致导致的启动报错，适合需要快速集成libssh2但又不愿在Windows下深入折腾编译过程的工程师。 在 Windows 上搞 C/C++ 开源库的编译，有时候真的挺磨人的。你搜“vs2017编译64位的libssh2库”，多半是已经踩到某个坑了：要么是拿到的二进制包架构不对，要么是链接时一堆莫名其妙的 LNK 错误，要么是 OpenSSL 版本跟你本地环境八字不合。这篇文章我就把整个流程拆开揉碎了讲一遍，从准备工作、CMake 配置、编译验证到集成进自己的 VS2017 项目，全部走一遍。如果你正打算给手头的 Windows 桌面工具加上 SFTP 传输或 SSH 远程执行的能力，这篇就是给你准备的实操手册。
1. 为什么非要自己编译 libssh2
1.1 直接拿现成二进制包有什么隐患
很多朋友的第一反应是“Github 上不是有 release 包吗？直接下载不香吗？”说实话，如果你只是临时写个小工具，那确实可以。但一旦你的项目要长期维护、要分发到客户机器上，现成二进制包的几个问题就很麻烦了：
- 版本滞后。网上很多预编译包还停留在几年前的老版本，老版本里可能存在已公开的安全漏洞，尤其是涉及加密通信的库，这个风险不能忽视。
- 依赖不透明。预编译包里绑定的 OpenSSL 是哪个版本、怎么编译的，你根本不知道。一旦你的程序里还链接了其他用到 OpenSSL 的库，分分钟符号冲突。
- 运行库不匹配。对方用 /MT 静态运行时编译，你在用 /MD 动态运行时，链接时就会爆出大量 LNK2038 之类的错误，处理起来比重新编译还痛苦。
所以，条件允许的情况下，自己用 vs2017 编译一份 64 位的 libssh2，一劳永逸。
1.2 64位编译的前置判断
现在做 Windows 开发，64 位基本是默认选项了。libssh2 本身是跨平台的纯 C 库，编译 64 位版本并没有特殊难度，但你要先确认几个前提：
- 你的目标程序是 x64 平台。这听起来像废话，但真的有人拿 32 位的 exe 去链接 64 位的静态库，然后在链接阶段懵了。
- 你本机的 VS2017 已安装了 x64 的 C++ 工具集。默认安装的 VS2017 是包含 x86 和 x64 两个平台的，但如果你自定义安装了组件，需要确认“VC++ 2017 工具集”和“Windows SDK”这两个项都在。
64 位编译的核心价值在于：地址空间更大、内存操作更宽裕，而且现代 Windows 系统对 64 位进程的兼容性和性能调度也更友好。如果你的软件要处理大文件传输或并发连接，64 位版本的优势非常明显。
1.3 工具链选择：CMake 是正路
libssh2 从 1.9 版本开始，官方就把 CMake 作为主要构建方式。VS2017 自带对 CMake 的良好支持，所以你不需要额外装什么工具。这里要解释一下为什么我不推荐“在 VS 里手工建一个工程然后把源码拖进去”：libssh2 的源码里有很多平台相关的条件编译逻辑，手工建工程很容易漏掉某些宏定义，导致编译出来的库在功能上有缺失。CMake 会把所有编译选项、宏定义、链接参数都自动处理妥当，省心得多。
2. 编译前的准备工作
2.1 核心依赖的取舍：OpenSSL 到底要不要
libssh2 的加密后端主要有两个：OpenSSL 和 mbedTLS。对于绝大多数场景，我建议直接上 OpenSSL。原因很简单：功能全、资料多、和 libssh2 的配合最成熟。
不过要留意 OpenSSL 的版本。libssh2 对 OpenSSL 1.1.0 以上版本支持得比较好。如果你手头有旧版 OpenSSL 1.0.2 的编译产物，建议换掉，1.0.2 早已停止维护，继续使用等于给自己的软件埋雷。
如果你只是测试 SSH 连接，不涉及证书校验的复杂场景，也可以编译不带加密后端的精简版本。但说实话，既然都折腾到编译这一步了，不如一步到位把 OpenSSL 也一起搞定。
2.2 获取源码的正确姿势
源码从官方仓库拉取就行：
- libssh2 的 GitHub release 页面下载 tar.gz 源码包
- OpenSSL 的源码可以从官网下载
下载后用 7-Zip 或 WinRAR 解压，注意路径上不要有中文和空格。我习惯把源码放在一个固定的目录，比如C:\libs\src\，这样 CMake 在查找依赖时不容易出幺蛾子。
2.3 构建目录与安装目录规划
CMake 有一个非常好的习惯：不允许在源码目录里直接生成构建文件。所以在源码根目录下建一个build文件夹，专门放 VS 的工程文件。这样源码目录始终干净，想重新配置时直接删掉 build 目录就行，不用重新解压。
安装目录建议单独规划，比如C:\libs\libssh2-x64。所有最终产物集中在这个目录下，后续在你自己的项目属性里配置引用路径时会非常清晰。默认的安装目录是C:\Program Files\libssh2，路径里带空格，在某些脚本场景下会踩坑，所以我在命令行里通常会显式指定安装前缀。
3. 完整构建流程解析
3.1 编译 OpenSSL：手动或找现成方案
如果不想自己编译 OpenSSL，可以使用第三方提供的预编译包，但必须注意版本和位数。我个人更倾向于自己编译，虽然过程稍微烦一点，但胜在可控。OpenSSL 在 Windows 下编译需要 Perl 环境，这个前置条件会让很多人卡住——又牵扯出 ActivePerl 或 StrawberryPerl 的安装问题。
这里有个变通之道：如果你的项目不需要 HTTPS 证书校验之类的功能，可以试试 libssh2 的 Windows 原生加密后端。这个方案不需要额外编译 OpenSSL。但就我测试的结果来看，原生后端的兼容性还是不如 OpenSSL 版。所以别偷懒，要么自己编译 OpenSSL，要么找一个你信得过的预编译版本。
3.2 用 CMake 生成 VS2017 工程文件
假设源码已经解压到C:\libs\src\libssh2-1.11.0，打开“VS2017 的开发人员命令提示符”（注意是 x64 版本的那个），依次执行以下命令：
cd C:\libs\src\libssh2-1.11.0 mkdir build cd build cmake .. -G "Visual Studio 15 2017 Win64" -DCMAKE_INSTALL_PREFIX=C:\libs\libssh2-x64 -DBUILD_SHARED_LIBS=ON -DCRYPTO_BACKEND=OpenSSL -DOPENSSL_ROOT_DIR=C:\libs\openssl-x64参数解释：
-G "Visual Studio 15 2017 Win64"：指定生成 64 位的 VS2017 工程。如果你在完整版的 cmake-gui 里操作，就是从“Visual Studio 15 2017”里选 x64 平台那一项。-DCMAKE_INSTALL_PREFIX：指定安装目录，后面cmake --install会把头文件、库文件统一拷贝到这里。-DBUILD_SHARED_LIBS=ON：编译动态库（DLL）。如果你想静态链接，改成 OFF。-DCRYPTO_BACKEND=OpenSSL：指定加密后端。-DOPENSSL_ROOT_DIR：让 CMake 找到 OpenSSL 的头文件和库文件位置。
如果 CMake 顺利跑通，build 目录下会生成libssh2.sln解决方案文件。
3.3 编译与安装
接着在同一个命令行窗口执行：
cmake --build . --config Release cmake --install . --config Release第一条命令用 Release 配置编译。第二条命令把生成的头文件和库文件安装到之前设置的安装目录。如果一切顺利，C:\libs\libssh2-x64下会出现include、bin、lib三个文件夹。
这里有个很关键的经验：编译动态库（DLL）时，Release 版本的 DLL 名字里可能不带后缀，但如果同时编译 Debug 版本，名字会带一个d后缀（比如libssh2.dll和libssh2d.dll）。如果你的项目需要在 Debug 和 Release 之间切换测试，建议把两个配置都编译一遍。
4. 编译结果的快速验证
4.1 静态库还是动态库
很多用到 libssh2 的工具会选择动态库方案，因为 exe 体积小、更新库文件不需要重编整个程序。但如果你想把它静态链接进自己的程序，部署时就不用带额外的 DLL。两种方案我都用过，这里说下代价：
- 动态库：程序体积小，但分发时要记得带上
libssh2.dll和它依赖的libssl-3-x64.dll、libcrypto-3-x64.dll。漏掉任何一个，运行时就崩给你看。 - 静态库：把所有依赖都揉进 exe，部署最省心，但链接时间变长，最终程序体积明显变大。
根据你自己的发布场景来选，没有绝对的好与坏。我自己做小工具时倾向于静态库，做插件系统时偏向动态库。
4.2 写一段测试代码验证库可用
编译成功不等于就能用，最好快速写一段代码验证一下。核心 API 就这么几步：初始化、建立 TCP 连接、SSH 握手、认证、执行命令、清理释放。下面这段代码可以当作验证样例：
#include <libssh2.h> #include <winsock2.h> #include <ws2tcpip.h> int main() { WSADATA ws; WSAStartup(MAKEWORD(2, 2), &ws); libssh2_init(0); SOCKET sock = socket(AF_INET, SOCK_STREAM, IPPROTO_TCP); sockaddr_in addr = { 0 }; addr.sin_family = AF_INET; addr.sin_port = htons(22); inet_pton(AF_INET, "192.168.1.100", &addr.sin_addr); if (connect(sock, (sockaddr *)&addr, sizeof(addr)) != 0) { printf("connect failed: %d\n", WSAGetLastError()); return 1; } LIBSSH2_SESSION *session = libssh2_session_init(); libssh2_session_handshake(session, sock); if (libssh2_userauth_password(session, "username", "password") != 0) { printf("auth failed\n"); } else { printf("auth ok\n"); } libssh2_session_disconnect(session, "bye"); libssh2_session_free(session); closesocket(sock); libssh2_exit(); WSACleanup(); return 0; }这个例子虽然简单，但能验证从编译到链接到运行时环境是否都正常。如果你用的是动态库版本，运行前记得把libssh2.dll和 OpenSSL 的 DLL 放到 exe 同目录下，或者在环境变量 PATH 里加上bin路径。
5. 集成到自己的 VS2017 项目
5.1 配置头文件与库文件路径
在自己项目里右键→属性，找到“VC++ 目录”：
- “包含目录”加上
C:\libs\libssh2-x64\include - “库目录”加上
C:\libs\libssh2-x64\lib
然后切到“链接器→输入→附加依赖项”，加上libssh2.lib。如果你的 OpenSSL 是动态库版，一般不需要显式链接 OpenSSL 的 lib，因为 libssh2 自己会处理对 OpenSSL 的引用；但如果你遇到链接错误，可以再手动加上libssl.lib和libcrypto.lib。
平台记得选 x64。有些人在这步忘了切换平台，Debug Win32 模式下编译，然后各种找不到头文件和库文件，排查半天才发现平台不对。
5.2 运行时库一致性
这是最容易踩坑的环节。检查两处：
- 你的项目属性里“C/C++ → 代码生成 → 运行库”究竟是
/MD还是/MT。 - libssh2 编译时用的哪个运行库。
如果 libssh2 用的是/MD，你项目里就必须也用/MD，否则链接时会报LNK2038: mismatch detected for 'RuntimeLibrary'。这个错误不会给你明确提示“你把 /MT 和 /MD 混用了”，只会说某个值不匹配，很多新手根本看不懂。解决办法很简单：重新用 CMake 编译 libssh2，把对应的运行库选项调整一致，或者改自己项目的运行库设置。
5.3 部署时别忘了 DLL 分发
如果你链接的是动态库版本的 libssh2，那么最终分发程序时要带齐这些文件：
libssh2.dll- OpenSSL 的 DLL（具体名字取决于版本，比如
libssl-3-x64.dll、libcrypto-3-x64.dll）
把 DLL 放在 exe 的同目录下是最省事的做法，别去搞什么系统目录，那是给自己找麻烦。一个小技巧：可以用dumpbin /dependents your_program.exe查看依赖的 DLL 清单，确认到底需要带哪些文件。VS2017 自带 dumpbin 工具，在开发人员命令提示符里直接能用。
6. 编译过程中的常见问题与排查技巧
6.1 CMake 找不到 OpenSSL
CMake 在配置阶段报Could NOT find OpenSSL，这是最常见的问题之一。原因多半是你没有指定-DOPENSSL_ROOT_DIR，或者指定的路径不对。我建议先确认 OpenSSL 的头文件确实在指定目录下，比如C:\libs\openssl-x64\include\openssl\ssl.h。还有一种情况是 CMake 找到了 OpenSSL 但版本太旧，libssh2 要求 OpenSSL 1.1.0 以上，旧版本会被直接拒掉。
6.2 编译报错 error C4996 sprintf 不安全
这个错误几乎人人会遇到。libssh2 的部分示例代码或老代码路径用了sprintf这类函数，而 VS2017 默认会把这类函数标记为不安全，要求用sprintf_s之类的安全版本。
最简单的处理方式：在你的项目里加上预处理器定义_CRT_SECURE_NO_WARNINGS，或者在 libssh2 的 CMake 配置里打开-DENABLE_WARNINGS=OFF。这不是什么大问题，但是很烦，而且会打断编译节奏，提前处理掉能省很多时间。
6.3 运行时提示缺少 libssh2.dll
编译链接都通过了，一运行就弹出“找不到 libssh2.dll”。这是典型的动态库部署问题，多半是你没有把 DLL 拷贝到 exe 目录，或者没有把 DLL 所在目录添加到环境变量。解决办法上面已经说过了，直接用 dumpbin 查依赖，把所有需要的 DLL 都放到 exe 同目录。
6.4 SSH 握手失败或者认证失败
如果编译验证正常，但连接服务器时失败，多半是 OpenSSL 版本冲突或服务器配置问题。建议先用ssh -v手动连一下目标服务器，确认服务器 SSH 服务正常。如果服务器没问题，再检查 libssh2 是否成功加载了 OpenSSL，可以在代码里调用libssh2_version(0)查看版本号，确认运行的是你编译进去的那个库。
6.5 性能问题：慢速传输的锅可能不在 libssh2
如果你的 SFTP 传输速度不理想，先别急着怪库。检查一下是否开了 Nagle 算法、TCP_NODELAY 选项，以及窗口大小设置是否合理。libssh2 在 Windows 上的性能瓶颈通常不在库本身，而在套接字参数和网络环境。
最后的实操心得
编译 libssh2 这件事，第一次做会觉得步骤很多，但只要理解了 CMake 的工作方式和几个关键参数的取舍，整个过程其实很机械。VS2017 + 64位 + libssh2 这个组合，在今天的 Windows 开发里依然是相当经典的搭配。我个人的建议是：不管你是做自动化部署工具、运维脚本还是文件同步软件，都尽量自己走一遍编译流程，哪怕最终决定用预编译包，也要知道它背后的依赖关系和编译选项是怎么来的，这样出了问题才不至于抓瞎。
本文还有配套的精品资源，点击获取
