简介面向 Windows 平台 C/C 开发者的 libssh 0.10.3 静态库由 VC2015vc140编译适合需要在自有程序中集成 SSH 远程登录、命令执行、文件传输与安全通信能力的项目也可用于学习 SSH 协议在 C/C 工程中的落地方式。SSH 协议通过加密保障远程会话安全该包可用于构建远程运维、自动化部署等场景的原型与工具对需要静态链接、减少额外 DLL 分发的工程较为友好。压缩包为 7z 格式共 10 个文件包含 7 个头文件、2 个 lib 静态库和 1 个 hpp 文件整体约 636KB头文件提供接口声明lib 可直接加入链接器输入目录按 include 与 debug/release 组织便于在 Visual Studio 工程中快速配置。静态链接可减少库依赖分发时的版本适配工作但仍需关注目标机的 VC2015 运行时库内保留日志与错误码机制便于排查连接、认证及链接阶段的问题。已有 177 人学习适合希望避开自行编译、直接开展 SSH 功能验证与项目集成的 Windows 开发者参考。1. 老工程加 SSH 能力卡在 VC2015 和 ssh.lib 上某开发者接手的旧系统锁死在 v140 工具集机器上只装了 VS2015第三方依赖清一色要求静态链接。他想给系统加一段 SSH 会话能力选型落到 libssh-0.10.3官方给的运行库是 DLL 形态头文件版本对不上编译期一路绿灯链接期一片 LNK2019。真正需要的东西很具体一个用 VC2015 编出来、运行库跟主工程对齐的 libssh-0.10.3 静态库也就是ssh.lib。这类活看着像体力活坑却极度集中一是 OpenSSL 静态库必须用同一套工具集、同一个运行库编二是/MT和/MD只要有一层不一致链接器就会用重复符号或运行期堆损坏来提醒你三是ssh.lib在 Windows 上不像静态库还牵涉LIBSSH_STATIC宏。手上压着老工程、又不想为它单独装一套新 VS 的人基本都会走这条路线。2. 编之前先把工具链钉死VS2015、CMake 与 OpenSSL 的版本配对这套环境最容易翻车的地方在工具链版本而非 libssh 本身。libssh-0.10.3 的 CMake 脚本会去探测 OpenSSL、zlib、线程库和一堆编译特性探测的逻辑没问题真正的问题在于探测到的东西是不是你想编进去的那个。如果机器上装了多个版本的 OpenSSL、或者 PATH 里存在另一套 SDKCMake 很可能静默抓错版本最后表现为编译全部通过、运行期连 TLS 握手都走不完。2.1 这套环境到底需要哪些组件先把要装的东西一次列全缺一样后面都要回头补组件建议版本或形态关键说明Visual Studio2015 Update 3v140 工具集32 位工程用 Win32 平台64 位要额外勾选 x64 工具链CMake3.13 及以上低于这个版本没有-S/-B参数只能手动 cd 到构建目录OpenSSL1.1.1 系列no-shared静态库必须和 libssh 用同一套工具集、同一个运行库编zlib1.2.x 静态库可选不启用时 SFTP 的压缩协商能力会缺一块Perl5.x只在编 OpenSSL 时需要Strawberry 或 ActivePerl 都行命令行环境VS2015 x86 原生工具命令提示符直接开 cmd 会找不到 cl.exe 和 nmake这里有一条重要的搭配原则所有静态库最终都要以/MT或/MD的身份混进同一个 exe所以从 OpenSSL 开始就得定下来用哪一套运行库。我一般会在最开始就把/MT定死后面 libssh、zlib、主工程全部照抄避免中途改主意导致整条链重编。2.2 OpenSSL 静态库必须先自己编出来现成的 OpenSSL 二进制包基本都是 DLL 形态跟着libcrypto.lib一起发的是导入库链接到静态库场景里会出现符号对不上的情况。所以第一步是拿源码编静态版本命令在 OpenSSL 源码根目录执行REM 先切到「VS2015 x86 原生工具命令提示符」再进 OpenSSL 源码目录 perl Configure VC-WIN32 no-shared no-asm ^ --prefixD:\deps\openssl-1.1.1 ^ --openssldirD:\deps\openssl-1.1.1\ssl nmake nmake installVC-WIN32指定 MSVC 32 位目标如果主工程是 x64这里换成VC-WIN64A同时用 x64 命令提示符启动。no-shared是这次的真正目标它让构建产物只有libcrypto.lib、libssl.lib这类静态库不出 DLL。no-asm是为了绕开ml.exe版本差异带来的汇编器报错在功能上不损失正确性只影响一部分性能纯客户端场景完全够用。--prefix这个参数要单独拎出来说它是后面 CMake 里OPENSSL_ROOT_DIR要指过去的目录安装完成后该目录下应当有include\openssl\opensslv.h和lib\libcrypto.lib缺哪一半都说明装得不完整。提示nmake install完成后不要立刻删源码目录之后排查版本错配时经常要回去比对opensslv.h里的版本宏。2.3 zlib 用 CMake 走一遍更省事zlib 本身没有复杂的构建系统但同样要保证运行库一致。我的习惯是不去用预编译包直接用 CMake 编一份cmake -G Visual Studio 14 2015 -A Win32 ^ -S D:\src\zlib ^ -B D:\build\zlib ^ -DCMAKE_INSTALL_PREFIXD:\deps\zlib ^ -DCMAKE_C_FLAGS_RELEASE/MT /O2 /DNDEBUG ^ -DCMAKE_C_FLAGS_DEBUG/MTd /Zi /Od /D_DEBUG cmake --build D:\build\zlib --config Release --target INSTALL这里出现的-DCMAKE_C_FLAGS_RELEASE是整套流程里最关键的一行。CMake 给 MSVC 生成的默认 Release 参数是/MD /O2 /DNDEBUG直接覆盖成/MT你编出来的 zlib 才是静态 CRT 版本。/DNDEBUG和/O2保留是有必要的去掉后会在 libssh 的配置检测里出现一些意料之外的断言行为。--target INSTALL会按前面CMAKE_INSTALL_PREFIX指定的位置把头和库铺好后面 libssh 的配置只认这个安装目录不认源码目录。如果主工程确定用/MD把上面两条CMAKE_C_FLAGS_*换成/MD和/MDd即可但改动要贯穿 OpenSSL、zlib、libssh 三层中途只改一层是最常见的错误。3. CMake 配置 libssh-0.10.3静态库的开关一个都不能漏libssh 的 CMake 选项不少而且默认值偏向“全都编”。默认开着动态库、开着示例、开着测试对于一个只需要ssh.lib的主工程来说这些多出来的构建目标只会拖长构建时间、增加报错面板。这一步要做的事就是把这些默认值逐个关掉只留静态库这一条线。3.1 源码目录和构建目录分开不要原地编先把目录规划固定下来后面所有命令都基于这套路径D:\src\libssh-0.10.3 源码保持干净 D:\src\zlib zlib 源码 D:\src\openssl-1.1.1 OpenSSL 源码 D:\build\libssh-0.10.3 libssh 的构建目录 D:\deps\openssl-1.1.1 OpenSSL 安装位置 D:\deps\zlib zlib 安装位置 D:\deps\libssh libssh 安装位置最终交付物在这里在源码目录里直接跑cmake .属于血泪经验级别的错误CMakeCache 会把绝对路径全部写死换个机器或改一次安装前缀就编不动想清理还得手动删一堆中间文件。分离构建目录之后配置错了直接把D:\build\libssh-0.10.3整个删掉重来源码不受影响。3.2 一行命令里每个参数都要知道它为什么在那下面是完整配置命令逐条解释放在后面cmake -G Visual Studio 14 2015 -A Win32 ^ -S D:\src\libssh-0.10.3 ^ -B D:\build\libssh-0.10.3 ^ -DCMAKE_INSTALL_PREFIXD:\deps\libssh ^ -DWITH_STATIC_LIBON ^ -DWITH_SHARED_LIBOFF ^ -DWITH_SERVERON ^ -DWITH_SFTPON ^ -DWITH_ZLIBON ^ -DZLIB_ROOTD:\deps\zlib ^ -DOPENSSL_ROOT_DIRD:\deps\openssl-1.1.1 ^ -DOPENSSL_USE_STATIC_LIBSTRUE ^ -DWITH_EXAMPLESOFF ^ -DWITH_TESTINGOFF ^ -DCMAKE_C_FLAGS_RELEASE/MT /O2 /DNDEBUG ^ -DCMAKE_C_FLAGS_DEBUG/MTd /Zi /Od /D_DEBUG-G Visual Studio 14 2015对应 VS2015 的生成器名14 是内部版本号写别的名字 CMake 会直接拒绝。-A Win32指定目标架构主工程是 64 位时改成-A x64同时前面的 OpenSSL 和 zlib 也必须是 x64 版本三层的架构必须完全一致混架构的报错通常要拖到链接期才出现。WITH_STATIC_LIBON和WITH_SHARED_LIBOFF是这次的核心开关。前者让构建系统产出ssh.lib后者把 DLL 目标整个摘掉免得误把ssh.dll当成交付物带走。WITH_SERVERON只在需要做服务端时才开纯客户端工程可以关掉能少编一批源文件。WITH_SFTPON建议保留多数人加 SSH 是为了传文件关掉之后 sftp 相关的头文件即使存在也没有实现。OPENSSL_ROOT_DIR必须显式指定不要指望 CMake 自己找。机器上同时装了多套 OpenSSL 时自动探测的结果完全不可预测而报错信息往往只写“找不到 OpenSSL”不告诉你它找的是哪个。OPENSSL_USE_STATIC_LIBSTRUE是在告诉探测逻辑优先接受.lib形态的库文件不加这一条CMake 可能把 DLL 导入库当成候选编出来的ssh.lib就会隐式依赖libcrypto.dll。WITH_EXAMPLESOFF和WITH_TESTINGOFF属于省事开关。示例工程和测试工程会引入额外的依赖比如某些测试组件在只需要库的场景里它们是纯粹的噪音来源关掉之后构建失败率明显下降。3.3 用 msbuild 编 Release 并装到指定目录配置成功后D:\build\libssh-0.10.3下会生成解决方案文件。接着编译并安装cd /d D:\build\libssh-0.10.3 REM 只编 Release|Win32/m 开并行机器内存吃紧时改成 /m:4 msbuild libssh.sln /m /p:ConfigurationRelease /p:PlatformWin32 REM 把头和库铺到 CMAKE_INSTALL_PREFIX 指定的目录 msbuild INSTALL.vcxproj /p:ConfigurationRelease /p:PlatformWin32/p:ConfigurationRelease和/p:PlatformWin32两个属性必须跟配置阶段选的生成器一致写成x64而实际是 Win32 时msbuild 会报“项目不存在该配置”这个错看着像工程坏了其实只是参数对不上。INSTALL.vcxproj是 CMake 自动生成的安装目标它会把libssh.h、callbacks.h、sftp.h、server.h、legacy.h和ssh.lib按include\libssh\、lib\的结构铺开。如果INSTALL目标不存在多半是配置阶段没给CMAKE_INSTALL_PREFIX回上一步补上再重新配置。编完之后去D:\deps\libssh\lib看一眼正常应该只有一个ssh.lib没有ssh.dll也没有ssh.exp。有ssh.dll就说明WITH_SHARED_LIB没关掉有ssh.exp说明还是在走动态库那套导出逻辑。4. 把 ssh.lib 挂进现有工程运行库、宏和路径三件事库编出来了只是第一步真正让主工程跑起来的是链接配置。这部分出问题的概率比编译阶段高因为编译错误会立刻停在某一行代码上而链接错误和运行期崩溃往往离现场很远排查成本高得多。4.1 运行库必须一致/MT和/MD混用会当场翻车先看一张对照表理解这两个开关到底在管什么选项CRT 形态典型后果/MT、/MTd静态链接 C 运行库exe 不依赖 VC 运行库体积略大/MD、/MDd动态链接 C 运行库需要目标机装对应运行库库/MT 工程/MD混用LNK2005 重复符号或运行期堆损坏库/MTd 工程/MT调试/发布混用断言失效、行为不一致极难定位libssh 在 Windows 上会大量申请和释放内存跨模块释放是最隐蔽的一类问题链接阶段可能只报几个警告运行时表现为ssh_new之后随机崩溃或者ssh_free时堆校验失败。判断方法很直接在 VS 的“项目属性 → C/C → 代码生成 → 运行库”里看主工程用的是什么再回D:\build\libssh-0.10.3里看编译时用的CMAKE_C_FLAGS_RELEASE两边必须完全一致。我一般直接翻CMakeCache.txt确认比猜靠谱。4.2 vcxproj 里要写的四组属性主工程如果是手写的 vcxproj可以直接在ItemDefinitionGroup里补属性避免每次图形界面点一遍ItemDefinitionGroup Condition$(Configuration)|$(Platform)Release|Win32 ClCompile RuntimeLibraryMultiThreaded/RuntimeLibrary AdditionalIncludeDirectoriesD:\deps\libssh\include;D:\deps\openssl-1.1.1\include;%(AdditionalIncludeDirectories)/AdditionalIncludeDirectories PreprocessorDefinitionsLIBSSH_STATIC;%(PreprocessorDefinitions)/PreprocessorDefinitions /ClCompile Link AdditionalLibraryDirectoriesD:\deps\libssh\lib;D:\deps\openssl-1.1.1\lib;%(AdditionalLibraryDirectories)/AdditionalLibraryDirectories AdditionalDependenciesssh.lib;libssl.lib;libcrypto.lib;ws2_32.lib;crypt32.lib;user32.lib;advapi32.lib;%(AdditionalDependencies)/AdditionalDependencies /Link /ItemDefinitionGroupRuntimeLibrary写MultiThreaded对应/MTDebug 配置对应MultiThreadedDebug。AdditionalIncludeDirectories里两个路径的顺序不要反过来OpenSSL 的头文件必须能被 libssh 的头找到顺序反了在某些包含链里会出现宏冲突。LIBSSH_STATIC这个宏是静态链接的关键。libssh 的公共头文件会根据这个宏决定函数声明前是否加__declspec(dllimport)不定义它的时候编译器仍然按导入库的语义生成符号引用链接器在ssh.lib里找不到对应的导入符号就会给出满屏的 LNK2019。这个坑非常典型库编对了、路径也对唯独少一个宏报错信息却指向“未解析的外部符号”。AdditionalDependencies里除了ssh.lib还要带上 OpenSSL 的两个静态库和几个系统库。ws2_32.lib是 Winsockcrypt32.lib和advapi32.lib是 OpenSSL 在 Windows 上做证书和随机数时依赖的少写会在链接期以 OpenSSL 符号未解析的形式暴露出来看着像 OpenSSL 没编好其实只是系统库没挂。4.3 最终要带走哪些文件编完之后需要从D:\deps里挑出真正要交付的东西别把整个源码树打进去文件来源目录用途ssh.libD:\deps\libssh\liblibssh 静态库本体libssh.h、callbacks.h、sftp.h、server.h、legacy.hD:\deps\libssh\include\libssh唯一需要暴露的头文件集合libssl.lib、libcrypto.libD:\deps\openssl-1.1.1\lib加密后端openssl头文件目录D:\deps\openssl-1.1.1\include\openssl供libssh.h内部包含zlib.lib、zlib.hD:\deps\zlib\lib、\include启用 zlib 时才需要注意D:\deps\libssh\include下还有一个libssh子目录工程里写#include libssh/libssh.h时AdditionalIncludeDirectories要指到上一级而不是直接指到libssh目录指错会让所有内部包含路径失效。5. 常见问题排查配置、编译、链接三段的翻车记录这套流程里真正耗时间的不是敲命令而是报错之后往哪看。下面五条是我在 VS2015 上编 libssh-0.10.3 时反复遇到的按现象、原因、解决拆开写方便对着日志直接定位。5.1 配置阶段OpenSSL 找到了但不是你要的那套现象CMake 报Could not find OpenSSL或者Found OpenSSL: ... (found version 3.x)但本机D:\deps里明明是 1.1.1。原因OPENSSL_ROOT_DIR没传或者传了但目录不是安装后的结构缺include\openssl\opensslv.h或lib\libcrypto.libCMake 会退回到环境变量、PATH 和各处缓存里去找抓到什么都算“成功”。缓存一旦写进CMakeCache.txt后续再怎么改参数都不会重新探测。解决先确认D:\deps\openssl-1.1.1\include\openssl\opensslv.h存在再带上-DOPENSSL_ROOT_DIR和-DOPENSSL_USE_STATIC_LIBSTRUE重新配置并且删掉整个构建目录而不是只删缓存文件。构建目录里的旧选项可能被其他探测结果带偏删干净重来一遍最省事。5.2 配置与编译阶段示例工程和编译器堆空间现象 A编译时报某示例工程引用的头文件不存在或者测试目标里出现一串未解析符号。原因WITH_EXAMPLES或WITH_TESTING默认值没有关示例和测试工程引入了额外依赖而这些依赖在只装了 SDK 的机器上往往不全。解决配置时显式加-DWITH_EXAMPLESOFF -DWITH_TESTINGOFF然后重新生成解决方案。这两个开关必须在配置阶段关编到一半再关等于白编。现象 Bmsbuild跑到一半报C1060: 编译器的堆空间不足。原因/m并行度过高而 VS2015 的cl.exe是 32 位进程地址空间有限同时编多个大文件时很容易撞上限。解决把并行度降到/m:4机器的物理内存小于 8GB 时降到/m:2。这个错和代码本身没关系纯属资源问题不用去动源码。现象 C链接 OpenSSL 时报符号名带后缀或明显不匹配的未解析符号。原因头文件版本和库版本不一致常见情况是 include 目录指向了另一套 OpenSSL或者 32 位头配 64 位库。解决用opensslv.h里的版本宏核对一遍确认AdditionalIncludeDirectories和AdditionalLibraryDirectories指向同一个安装前缀且架构一致。5.3 链接与运行阶段LNK2019、LNK2005 和运行期崩溃现象 A链接期满屏LNK2019: 无法解析的外部符号 _ssh_new、_ssh_options_set等。原因三种可能混在一起——没定义LIBSSH_STATIC导致按 dllimport 语义生成引用AdditionalLibraryDirectories里没加 libssh 的 lib 目录AdditionalDependencies里写的是libssh.lib而实际产物叫ssh.lib。解决按顺序核对先补LIBSSH_STATIC再确认依赖写的是ssh.lib。这一项排查率高到值得写进团队的工程模板里。现象 B链接期报LNK2005: 已经在 libcmt.lib 中定义或者一堆 CRT 符号重复。原因/MT和/MD混用或者 Debug 配置里混进了 Release 版的静态库。解决统一运行库Release 配 Release 库Debug 配 Debug 库。别图省事拿一份ssh.lib同时喂给两个配置调试版和发布版的 CRT 不能互换。现象 C程序能编能链运行时在ssh_new附近随机崩溃或者ssh_free时堆校验失败。原因多半还是 CRT 不一致静态库和主工程各持一份堆跨模块释放内存破坏了堆结构。少数情况是 OpenSSL 的静态库和 libssh 不是同一套运行库编的。解决把 OpenSSL、zlib、libssh 三层的CMAKE_C_FLAGS_*全部翻出来比对确认完全一致后整条链重编。这类问题改一处没用必须从 OpenSSL 开始重来。6. 验证 ssh.lib 真能跑通一个不用连服务器的最小验证程序库能不能用不看编出来的文件大小看链接之后能不能初始化。我一般会写一个不到三十行的验证程序只调用初始化和参数设置不发起任何网络连接所以不需要目标机器上有 SSH 服务。这比直接拿业务代码去试要快得多出问题时也容易判断是哪一层的问题。#include stdio.h #include libssh/libssh.h int main(void) { /* 初始化库返回 SSH_OK 说明 ssh.lib 真正被链接并可运行 */ if (ssh_init() ! SSH_OK) { printf(ssh_init failed\n); return 1; } /* 打印版本能输出说明静态库里的符号解析成功 */ printf(libssh version: %s\n, ssh_version(0)); ssh_session s ssh_new(); if (s NULL) { printf(ssh_new failed\n); ssh_finalize(); return 1; } /* 只写参数不建立连接避免依赖真实的 SSH 服务 */ ssh_options_set(s, SSH_OPTIONS_HOST, 127.0.0.1); int port 22; ssh_options_set(s, SSH_OPTIONS_PORT, port); ssh_free(s); ssh_finalize(); return 0; }ssh_init返回SSH_OK是第一个门槛它内部会做线程和加密库的初始化/MT混用时经常就崩在这一步。ssh_version(0)传 0 表示不校验最低版本直接返回版本字符串能打印出0.10.3说明头文件和库文件对得上。SSH_OPTIONS_PORT要传int的地址而不是值这是 libssh 参数接口的惯例传错会读到栈上的垃圾值。ssh_free和ssh_finalize都调一遍是为了把资源释放路径也过一遍堆损坏类问题在这一步更容易暴露。编译这个验证程序用命令行最直接cl /nologo /MT /ID:\deps\libssh\include /ID:\deps\openssl-1.1.1\include ^ test_link.c /link ^ /LIBPATH:D:\deps\libssh\lib ^ /LIBPATH:D:\deps\openssl-1.1.1\lib ^ ssh.lib libssl.lib libcrypto.lib ws2_32.lib crypt32.lib user32.lib advapi32.lib/MT在这里不能省它要和库的编译选项一致。/I指到include的上一级这样#include libssh/libssh.h才能解析到。/link之后的系统库少写一个都可能出现 OpenSSL 符号未解析报错看起来像 OpenSSL 没编好实际是链接参数不全。跑通之后正常输出只有两行版本号和退出码 0。如果版本号打印出来但ssh_new返回空重点查 OpenSSL 的静态库是不是同一套运行库如果连版本号都打不出来回到第五章的 LNK2019 那一条八成是少了LIBSSH_STATIC。从那以后我每次编这类静态库都会先把这个三十行的验证程序跑一遍再往主工程里挂宁可多花十分钟也不愿在一堆业务崩溃现场里回头怀疑库。希望帮到你。本文还有配套的精品资源点击获取
