VS2017编译libssh2：解决CMake找不到OpenSSL与x64链接失败

简介：本资源是面向Windows平台C/C++开发者的libssh2库64位编译成果包，专为VS2017环境定制，解决在64位Windows应用中集成SSH2协议支持的核心依赖问题，适用于远程安全通信、SFTP文件传输及嵌入式SSH客户端开发等实际场景。压缩包共115个文件，含109个头文件（.h）——涵盖libssh2核心接口与OpenSSL兼容层（如ssl.h、evp.h、tls1.h、ec.h等），3个静态库文件（.lib）用于链接，2个运行时DLL（libcrypto-1_1-x64.dll、libssl-1_1-x64.dll）保障加密功能，另有1个示例源码（main.cpp）便于快速验证调用流程；整体体积仅2.14MB，轻量易集成。已有1517人学习下载，资源结构即开即用：无需重复编译，可直接将头文件目录纳入包含路径、链接libssh2.lib并部署对应DLL，显著降低跨平台网络库接入门槛。

1. VS2017 编译 libssh2：一个看似简单却让无数人卡在 CMake 报错、OpenSSL 链接失败、x64 平台切换失灵的“经典翻车现场”

你是不是也遇到过：项目里突然要加 SFTP 文件传输，技术方案定了 libssh2，文档写得清清楚楚“支持 Windows”，结果一打开 VS2017 就懵了——CMake GUI 点 Configure 直接红屏，报Could NOT find OpenSSL，哪怕你明明装了 OpenSSL 1.1.1w；或者好不容易过了 OpenSSL 这关，生成的工程却是 Win32（x86）平台，一编译就提示LNK2019: unresolved external symbol __imp__BIO_new；更玄学的是，改完平台再 Configure，CMake 又清空缓存重来，前功尽弃。这不是小众需求，而是某跨平台系统在某高校实验室做内网设备管理模块时的真实起点，也是某公司做远程运维 SDK 时绕不开的底层依赖。它不难，但版本链极敏感：VS2017 对应的 MSVC 工具集是 v141，libssh2 1.10.x 起已默认要求 OpenSSL 1.1.1+，而官方预编译包又只提供 x86 或静态链接版——你要的，是一个能被你的 x64 Release 工程直接#include <libssh2.h>并#pragma comment(lib, "libssh2.lib")的干净动态库。本文全程基于 VS2017 Community（v15.9.39）、CMake 3.22.1、OpenSSL 1.1.1w、libssh2 1.10.0，所有路径、参数、错误日志均来自真实构建过程，不跳步、不省略、不假设你“已经装好”。

2. 环境准备：三个必须亲手验证的组件及其精确版本锚点

2.1 安装 VS2017 并确认 v141 工具集可用

VS2017 的关键不是“装了”，而是“装对了组件”。很多开发者用默认选项安装后发现没有x64 Native Tools Command Prompt for VS 2017，或 CMake 找不到cl.exe，根源在于缺失C++ 通用 Windows 平台工具和Windows 10 SDK（10.0.17763.0 或更高）。

提示：不要用 VS Installer 的“修改”功能临时勾选——它可能不刷新环境变量。建议卸载后重装，勾选以下三项：

• Desktop development with C++（必选，含 v141 工具集）
• CMake tools for Visual Studio（非必须，但能避免命令行手动指定生成器）
• Windows 10 SDK (10.0.17763.0)（libssh2 的winsock2.h兼容性依赖此版本）

验证方式：打开「x64 Native Tools Command Prompt for VS 2017」，执行：

cl

应输出类似Microsoft (R) C/C++ Optimizing Compiler Version 19.16.27045 for x64。若报cl 不是内部或外部命令，说明环境变量未加载，需重启命令提示符或手动运行：

"C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\VC\Auxiliary\Build\vcvarsall.bat" x64

2.2 下载并编译 OpenSSL 1.1.1w（x64 动态库版）

libssh2 1.10+ 强依赖 OpenSSL 1.1.1+，且必须与你的目标平台（x64）和运行时（/MD 或 /MT）严格匹配。官方预编译包多为 x86 或静态库（.lib），直接链接会导致 LNK2001/LNK2019。我们必须自己编译 OpenSSL x64 动态版。

步骤清单：

1. 下载 OpenSSL 1.1.1w 源码： https://www.openssl.org/source/openssl-1.1.1w.tar.gz ，解压到D:\deps\openssl-1.1.1w

2. 打开「x64 Native Tools Command Prompt for VS 2017」，进入源码目录：

   cd /d D:\deps\openssl-1.1.1w

3. 配置为 x64 动态库（关键！no-static+VC-WIN64A）：

   perl Configure VC-WIN64A no-shared no-static --prefix=D:\deps\openssl-x64 --openssldir=D:\deps\openssl-x64

   • VC-WIN64A：强制 x64 构建（不是VC-WIN32）
   • no-shared：先禁用共享库（即 DLL），因为 libssh2 默认链接 OpenSSL 静态库；但我们后续会启用它，所以这步只是确保配置无误
   • --prefix：指定安装根目录，避免污染系统路径

4. 生成 Makefile 并编译：

   nmake nmake install

编译成功后，D:\deps\openssl-x64下应有include\openssl\和lib\目录，其中lib\libcrypto.lib和lib\libssl.lib是我们需要的导入库（.lib），对应bin\libcrypto-1_1-x64.dll（运行时需部署）。

2.3 获取 libssh2 源码并确认分支兼容性

libssh2 官方 GitHub 主干（main 分支）在 2023 年后已移除对 VS2017 的 CI 支持，但1.10.0 tag（2021年12月发布）是最后一个明确标注支持 VS2017 的稳定版。切勿使用 master 或 1.11.x ——它们默认启用 C11 特性，VS2017 的 MSVC v141 编译器不完全支持_Generic等语法，会直接报错error C2061: syntax error: identifier '_Generic'。

下载地址：
https://github.com/libssh2/libssh2/archive/refs/tags/libssh2-1.10.0.tar.gz
解压至D:\deps\libssh2-1.10.0

验证关键文件：打开D:\deps\libssh2-1.10.0\CMakeLists.txt，搜索cmake_minimum_required，应为VERSION 3.10（VS2017 自带 CMake 3.10+ 兼容）；搜索project(，应为project(libssh2 C)，无CXX——这是纯 C 库，避免 C++ 运行时冲突。

3. CMake 配置：四步精准控制平台、运行时与 OpenSSL 路径

3.1 创建独立构建目录并启动 CMake GUI

永远不要在源码目录下cmake .！libssh2 的 CMake 脚本会生成大量中间文件，混入源码树后极易导致缓存污染。创建干净构建目录：

mkdir D:\build\libssh2-x64 cd /d D:\build\libssh2-x64

然后启动 CMake GUI（非命令行）：

• Where is the source code:D:/deps/libssh2-1.10.0
• Where to build the binaries:D:/build/libssh2-x64
• 点击Configure→ 弹出窗口选择Visual Studio 15 2017 Win64（注意末尾的Win64！不是Visual Studio 15 2017）

为什么必须用 GUI？因为 VS2017 的 CMake 工具链对CMAKE_GENERATOR_PLATFORM的识别不稳定，命令行cmake -G "Visual Studio 15 2017 Win64"有时会降级为 Win32。GUI 强制锁定平台。

3.2 关键变量设置：覆盖默认值，直击三大痛点

首次 Configure 后，CMake 会报红（Could NOT find OpenSSL），此时不要慌——这是预期行为。在 GUI 变量列表中，找到并修改以下项（勾选Advanced才可见）：

注意：OPENSSL_SSL_LIBRARY和OPENSSL_CRYPTO_LIBRARY必须是.lib文件路径，不是目录！CMake 会自动推导对应的.dll名称（libssl-1_1-x64.dll），但不会帮你拷贝 DLL。

3.3 二次 Configure 与 Generate：确认无红标后生成 VS 工程

修改完上述变量，点击Configure。这次应无红色报错，底部日志显示：

-- Found OpenSSL: D:/deps/openssl-x64/lib/libssl.lib (found version "1.1.1w") -- Configuring done -- Generating done -- Build files have been written to: D:/build/libssh2-x64

点击Generate，CMake 会在D:\build\libssh2-x64下生成libssh2.sln。

验证生成结果：打开该目录，检查是否存在：

• libssh2.sln（Visual Studio 解决方案）
• CMakeCache.txt（确认BUILD_SHARED_LIBS:BOOL=ON）
• CMakeFiles/下有libssh2.dir/（证明目标已注册）

4. 编译与安装：从 sln 编译到部署 DLL 的完整闭环

4.1 在 Visual Studio 中编译解决方案

双击D:\build\libssh2-x64\libssh2.sln，用 VS2017 打开。此时解决方案资源管理器中应有多个项目，重点关注：

• libssh2（主动态库项目，生成libssh2.dll和libssh2.lib）
• example（示例程序，用于后续验证）
• tests（测试套件，可跳过）

编译前必做三件事：

1. 顶部工具栏，将Solution Configuration设为Release，Solution Platform设为x64（不是Active Solution Platform下拉框里的默认值！）
2. 右键libssh2项目 →Properties→Configuration Properties→General→ 确认Configuration Type为Dynamic Library (.dll)
3. 右键libssh2→Build（或按Ctrl+Shift+B）

编译过程约 1–2 分钟。成功后，输出窗口显示========== Build: 1 succeeded, 0 failed, 0 up-to-date, 0 skipped ==========。

4.2 提取编译产物：DLL、LIB、头文件的物理位置

编译完成后，产物分散在多个子目录。按用途整理：

提示：不要直接引用D:\deps\libssh2-1.10.0\include作为项目包含目录——源码目录可能被清理。标准做法是新建D:\myproject\3rdparty\libssh2\include，将libssh2-1.10.0\include\libssh2.h及其子目录libssh2\全部复制过去。

4.3 安装到自定义前缀（可选但推荐）

libssh2 的 CMake 支持INSTALL目标，可一键部署头文件、库、DLL 到统一目录，避免路径混乱：

1. 在 VS2017 中，右键解决方案 →Build Solution（确保所有项目已编译）

2. 右键INSTALL项目 →Build

   若无INSTALL项目，说明 CMake 未启用安装规则。回到D:\build\libssh2-x64，用文本编辑器打开CMakeCache.txt，确认CMAKE_INSTALL_PREFIX:PATH=D:/install/libssh2-x64已设置，然后重新Configure+Generate。

3. 成功后，D:\install\libssh2-x64下结构为：

   include/ libssh2.h libssh2/ publickey.h sftp.h ... lib/ libssh2.lib bin/ libssh2.dll libssl-1_1-x64.dll libcrypto-1_1-x64.dll

此目录可直接作为你项目的第三方依赖根目录。

5. 常见问题排查：五条血泪经验，专治 CMake 红屏、LNK2019、平台错乱

5.1 现象：CMake Configure 报Could NOT find OpenSSL，但路径明明正确

原因：OPENSSL_INCLUDE_DIR指向了D:/deps/openssl-x64（根目录），而非D:/deps/openssl-x64/include；或lib/下缺少libssl.lib（因 OpenSSL 编译时未执行nmake install）。
解决：

• 用文件管理器确认D:/deps/openssl-x64/include/openssl/ssl.h存在；
• 运行dir D:\deps\openssl-x64\lib\*.lib，确保输出含libssl.lib；
• 在 CMake GUI 中，删除OPENSSL_*所有变量（右键 →Delete），重新输入完整路径。

5.2 现象：VS2017 编译libssh2时大量LNK2019: unresolved external symbol __imp__BIO_new

原因：libssh2 链接了 OpenSSL 的导入库，但 OpenSSL 本身是静态编译（no-shared），导致符号未导出；或libssh2项目属性中Configuration Type错设为Application (.exe)。
解决：

• 重新编译 OpenSSL，必须用no-shared配置（见 2.2 节），nmake install后lib/下应有libssl.lib；
• 在 VS 中右键libssh2→Properties→General→Configuration Type必须为Dynamic Library (.dll)。

5.3 现象：生成的libssh2.dll无法被dumpbin /dependents识别 OpenSSL 依赖

原因：libssh2项目链接器设置中，Additional Dependencies未包含libssl.lib和libcrypto.lib；或 CMake 生成时未传递-lssl -lcrypto。
解决：

• 右键libssh2→Properties→Linker→Input→Additional Dependencies，添加：
  libssl.lib;libcrypto.lib
• 同时在Linker→General→Additional Library Directories添加：
  D:\deps\openssl-x64\lib

5.4 现象：example项目编译通过，但运行时报0xc000007b（架构不匹配）

原因：example.exe是 x64，但加载了 x86 版 OpenSSL DLL（如libssl-1_1.dll而非libssl-1_1-x64.dll）；或PATH环境变量指向了其他目录下的 x86 DLL。
解决：

• 用Process Monitor（Sysinternals 工具）过滤example.exe的CreateFile事件，看它实际加载了哪个libssl*.dll；
• 将D:\deps\openssl-x64\bin\加入PATH最前面，或直接把libssl-1_1-x64.dll和libcrypto-1_1-x64.dll复制到example.exe同目录。

5.5 现象：CMake Generate 后，VS2017 中libssh2项目平台显示Win32，手动改为x64后编译失败

原因：CMake Generator 选择错误。Visual Studio 15 2017（无 Win64）会生成 Win32 工程，即使你在 VS 里强行切换平台，MSBuild 仍调用 x86 工具链。
解决：

• 彻底删除D:\build\libssh2-x64目录；
• 重新创建空目录；
• CMake GUI 中，Configure时必须选择Visual Studio 15 2017 Win64（名称含 Win64）；
• 再次 Configure，确认CMAKE_GENERATOR_PLATFORM:INTERNAL=Win64出现在CMakeCache.txt中。

6. 验证与集成：用一个最小 SFTP 示例跑通整个链路

6.1 编写验证代码：50 行完成 SFTP 连接与文件列表

在D:\build\libssh2-x64\example\下新建sftp_test.c（复用 libssh2 自带示例框架）：

// sftp_test.c #include <libssh2.h> #include <libssh2_sftp.h> #include <stdio.h> #include <stdlib.h> #include <string.h> int main(int argc, char *argv[]) { const char *host = "127.0.0.1"; // 替换为你的 SFTP 服务器 const char *user = "test"; const char *pass = "password"; LIBSSH2_SESSION *session; LIBSSH2_SFTP *sftp; LIBSSH2_SFTP_HANDLE *handle; struct libssh2_sftp_attributes attrs; // 初始化 libssh2 libssh2_init(0); // 创建 socket（简化版，生产环境需用阻塞/非阻塞 socket） int sock = socket(AF_INET, SOCK_STREAM, 0); struct sockaddr_in sin = {0}; sin.sin_family = AF_INET; sin.sin_port = htons(22); sin.sin_addr.s_addr = inet_addr(host); if (connect(sock, (struct sockaddr*)&sin, sizeof(sin)) != 0) { fprintf(stderr, "Failed to connect\n"); return -1; } // 建立 SSH 会话 session = libssh2_session_init(); libssh2_session_handshake(session, sock); libssh2_userauth_password(session, user, pass); // 初始化 SFTP sftp = libssh2_sftp_init(session); if (!sftp) { fprintf(stderr, "Unable to init SFTP session\n"); return -1; } // 打开根目录 handle = libssh2_sftp_opendir(sftp, "/"); if (handle) { fprintf(stdout, "SFTP connection OK. Root dir listing:\n"); char buf[1024]; while (libssh2_sftp_readdir(handle, buf, sizeof(buf), &attrs) > 0) { printf(" %s\n", buf); } libssh2_sftp_closedir(handle); } else { fprintf(stderr, "Failed to open root dir\n"); } // 清理 libssh2_sftp_shutdown(sftp); libssh2_session_disconnect(session, "Normal shutdown"); libssh2_session_free(session); closesocket(sock); libssh2_exit(); return 0; }

6.2 在 VS2017 中编译并链接此示例

1. 将sftp_test.c加入example项目（右键example→Add→Existing Item）

2. 右键example→Properties→Configuration Properties：

   • General→Configuration Type:Application (.exe)
   • C/C++→General→Additional Include Directories:
     D:\deps\libssh2-1.10.0\include;D:\deps\openssl-x64\include
   • Linker→General→Additional Library Directories:
     D:\build\libssh2-x64\Release;D:\deps\openssl-x64\lib
   • Linker→Input→Additional Dependencies:
     libssh2.lib;libssl.lib;libcrypto.lib;ws2_32.lib

3. 编译example项目，生成example.exe

6.3 运行时部署与调试技巧

生成的example.exe依赖四个 DLL：

• libssh2.dll（你的编译产物）
• libssl-1_1-x64.dll,libcrypto-1_1-x64.dll（OpenSSL）
• VCRUNTIME140.dll,MSVCP140.dll（VS2017 运行时）

部署方案（二选一）：

• 方案 A（开发机）：将D:\build\libssh2-x64\Release\libssh2.dll和D:\deps\openssl-x64\bin\*.dll全部复制到example.exe同目录；
• 方案 B（目标机）：安装 Microsoft Visual C++ 2015–2019 Redistributable (x64) ，并将 OpenSSL DLL 放入C:\Windows\System32（不推荐）或应用目录。

调试技巧：

• 用depends.exe（Dependency Walker）打开example.exe，确认所有依赖 DLL 的架构均为x64，且无红色问号；
• 若报libssh2_session_handshake返回NULL，用 Wireshark 抓包确认 TCP 22 端口是否可达；
• 在代码中插入fprintf(stderr, "Error: %d\n", libssh2_session_last_error(session, NULL, 0, 0));获取具体错误码。

从那以后我每次给新同事配 libssh2 环境，都强制走一遍「VS2017 Win64 生成器 → OpenSSL 1.1.1w no-shared 编译 → CMake GUI 手动填 OPENSSL_* 路径 → example.exe 验证」这个闭环，哪怕多花 15 分钟，也比后期在客户现场 debug LNK2019 强十倍。希望帮到你。

本文还有配套的精品资源，点击获取