企业官网建设流程全解析

• 开发工具

导读

libgit2 是一个跨平台、可链接的 Git 核心库纯 C 实现，通常通过 CMake 从源码构建。在配置阶段最常见的失败点与 HTTPS/TLS 支持有关——CMake 会尝试自动探测系统的 SSL/TLS 库，一旦找不到就会中断配置。本文以 docs/troubleshooting.md 为核心，深入讲解「Asked for OpenSSL TLS backend, but it wasn't found」这类错误的成因、两种标准解法，并结合 cmake/SelectHTTPSBackend.cmake 等源码剖析后端自动选择机制，帮助你独立排查和解决构建配置问题。

一、错误现象与直接原因

在从源码构建 libgit2 时，执行：

$ mkdir build && cd build $ cmake ..

如果环境中缺少 SSL/TLS 开发库，CMake 配置会在检查依赖阶段直接报错并中止：

Asked for OpenSSL TLS backend, but it wasn't found

这句错误信息来自 cmake/SelectHTTPSBackend.cmake：

elseif(USE_HTTPS STREQUAL "openssl") if(NOT OPENSSL_FOUND) message(FATAL_ERROR "Asked for OpenSSL TLS backend, but it wasn't found") endif()

根本原因：libgit2 默认总是开启 HTTPS 支持。CMake 找不到你系统上的 OpenSSL（或其头文件、库文件），因此无法满足默认配置需求，于是报错退出。也就是说，这不是代码问题，而是构建环境的依赖缺失或探测失败。

从源码结构看，HTTPS 在 libgit2 中不是一个可选附加功能，而是默认构建的一部分：顶层 CMakeLists.txt 中USE_HTTPS的默认值即为ON，对应的 TLS 流（TLS stream）实现位于 src/libgit2/streams 目录下（openssl.c、mbedtls.c、stransport.c、schannel.c、tls.c等）。

二、默认 HTTPS 与后端自动选择机制

要理解这个错误，先要明白 libgit2 是如何决定使用哪个 TLS 后端的。这一逻辑完全集中在 cmake/SelectHTTPSBackend.cmake 中：

1. 配置阶段先探测候选依赖：find_package(OpenSSL)与find_package(mbedTLS)（macOS/iOS 上还会探测 Security 与 CoreFoundation 框架）；
2. USE_HTTPS为空时被强制设为ON（cmake/SelectHTTPSBackend.cmake）；
3. 当USE_HTTPS=ON（未显式指定后端）时，按以下优先级自动挑选（cmake/SelectHTTPSBackend.cmake）：

因此「Asked for OpenSSL TLS backend, but it wasn't found」出现的情形通常是：非 macOS、非 Windows 的 Unix 类系统上，OpenSSL 被优先探测但失败，且 mbedTLS 也未安装，最终在 OpenSSL 分支直接报错退出。与之对称的还有一条 mbedTLS 分支的错误信息Asked for mbedTLS backend, but it wasn't found（cmake/SelectHTTPSBackend.cmake）。

运行时层面，编译期通过宏（如GIT_HTTPS_OPENSSL、GIT_HTTPS_MBEDTLS、GIT_HTTPS_SECURETRANSPORT、GIT_HTTPS_SCHANNEL）决定实际链接哪个 TLS 实现，src/libgit2/streams/tls.c 中的git_tls_stream_new()会根据这些宏选择对应的流构造函数。

三、解决方案一：安装系统的 OpenSSL 开发库（推荐）

官方文档给出的首要建议是：为你的系统安装 OpenSSL 开发包。以 Debian/Ubuntu 系为例：

$ sudo apt-get install libssl-dev

其他发行版/平台的对应包（以官方常见说明为准）大致对应关系如下：

• Debian / Ubuntu：libssl-dev
• RHEL / CentOS / Fedora：openssl-devel
• macOS（Homebrew）：openssl（brew 安装后通常还需配合OPENSSL_ROOT_DIR指定路径，见下文第五节）
• Windows：默认走winhttp后端，一般不依赖 OpenSSL

安装完成后，重新从干净的 build 目录执行cmake ..即可通过探测。如果系统里其实已经装了 OpenSSL 但 CMake 没找到，多半是路径问题，见第五节「依赖定位」。

四、解决方案二：完全禁用 HTTPS 支持

如果只是本地开发调试，不需要 HTTPS 网络功能，可以显式关闭 HTTPS 来跳过所有 TLS 后端的探测：

$ cmake -DUSE_HTTPS=OFF ..

在 cmake/SelectHTTPSBackend.cmake 中，USE_HTTPS=OFF会设置GIT_HTTPS 0，同时通过add_feature_info输出 "HTTPS support is disabled"，从而不链接任何 TLS 后端、不触发 FATAL_ERROR。

需要说明的是，USE_HTTPS=OFF会连带禁用https://协议能力，http://协议仍可用（USE_HTTP独立控制，见 CMakeLists.txt）。此外 README 中的 可选依赖说明 也指出：HTTPS 在 macOS/Windows 上由系统库提供，在 Unix 上由 OpenSSL 或 mbedTLS 提供。因此只有在确实不需要 TLS 加密传输时才建议关闭，生产环境请优先安装依赖。

五、解决方案三：显式指定后端与依赖定位

5.1 指定其他 TLS 后端

与其依赖自动探测，不如在配置时明确告诉 CMake 使用哪个后端。顶层 CMakeLists.txt 定义的合法取值包括：

例如指定 mbedTLS：

$ cmake -DUSE_HTTPS=mbedTLS ..

从源码看，mbedTLS 分支还支持通过CERT_LOCATION显式指定默认证书位置，否则会尝试调用openssl version -d自动探测常见 CA 证书路径（ca-bundle.pem、cert.pem、certs/ca-certificates.crt、certs/ca.pem等，见 cmake/SelectHTTPSBackend.cmake）。

5.2 依赖在非标准路径时的定位

如果 OpenSSL 已安装但 CMake 找不到（例如 Homebrew 安装的 OpenSSL、交叉编译环境、自定义安装前缀），可以通过_ROOT_DIR类选项指定位置。README 的 Locating Dependencies 一节给出了官方示例：

$ cmake -DOPENSSL_ROOT_DIR=/tmp/openssl-3.3.2 ..

mbedTLS 的探测逻辑同样支持MBEDTLS_ROOT_DIR提示路径（见 cmake/FindmbedTLS.cmake）。更细粒度地，还可以直接指定库文件位置：OPENSSL_SSL_LIBRARY、OPENSSL_CRYPTO_LIBRARY、ZLIB_LIBRARY等（见 README.md）。

5.3 查看当前所有配置项

配置完成后，可用cmake -L列出所有构建选项及其当前取值，快速确认USE_HTTPS等变量的实际状态（见 README.md）：

$ cmake -L

六、配置成功后的验证与运行

依赖问题解决、cmake ..顺利通过后：

$ cmake --build . $ ctest -V # 从 build 目录运行测试

也可直接运行测试程序并指定用例组，例如./libgit2_tests -sindex运行索引相关测试（详见 README.md）。若构建过程中仍遇到编译错误，可先确认cmake与 Python（测试框架依赖）已加入PATH，并使用较新的 CMake 版本，这些是 README.md 列出的基本构建前提。

提示：官方文档建议在干净的源码树上构建时不应出现任何测试失败（见 README.md）。若出现失败，可携带构建配置、平台信息与复现步骤向项目维护者反馈。

七、小结：排查路线图

本质上，Asked for OpenSSL TLS backend, but it wasn't found是「默认开启 HTTPS + 依赖探测失败」的必然结果。理解 cmake/SelectHTTPSBackend.cmake 的后端选择优先级，就能在三分钟内定位问题并选择最合适的解法：装依赖、关 HTTPS，或显式切换后端。

• 开发工具