curl 技术指南：多协议数据传输命令行工具与 libcurl 库的架构、构建与使用详解

本文以 curl 仓库根目录 README 为主线，介绍 curl/libcurl 的定位、支持的完整协议集、仓库代码布局、从源码构建安装的全流程（Autotools 与 CMake）、依赖版本基线以及安全与许可规范。读完后你将能够：准确说明 curl 工具与 libcurl 库的边界、将每个协议对应到具体源码实现位置、按仓库文档独立完成源码级构建与 TLS 后端选择，并理解版本、依赖与安全响应机制。

一、curl 是什么：一个工具加一个库

README 对项目的定义非常凝练：curl 是一个使用 URL 语法从服务器传输数据或向服务器传输数据的命令行工具，而 libcurl 是 curl 完成工作所依赖的库，可供第三方软件直接调用。两者共用同一套协议实现，但交付形态不同：

• curl 命令行工具：面向终端用户，负责解析命令行参数、处理输出与进度显示，源码位于 src/ 目录；
• libcurl 库：面向开发者，公开 API 头文件全部位于 include/curl/ 目录，核心实现在 lib/ 目录。

当前仓库的版本状态可以从 include/curl/curlver.h 中确认：

#define LIBCURL_VERSION "8.22.0-DEV"
#define LIBCURL_VERSION_MAJOR 8
#define LIBCURL_VERSION_MINOR 22
#define LIBCURL_VERSION_PATCH 0
#define LIBCURL_VERSION_NUM 0x081600

其中 LIBCURL_VERSION_NUM 采用 0xXXYYZZ 的 24 位十六进制编码，程序可用大于/小于直接比较版本新旧；-DEV 后缀表明该快照处于两次正式发布之间的开发主线。

1.1 仓库目录布局

结合 README 的模块划分，仓库顶层结构可以这样理解：

目录/文件	角色
src/	curl 命令行工具源码，入口为 src/tool_main.c
lib/	libcurl 核心实现，含协议、传输、连接缓存、过滤器等模块
lib/vtls/、lib/vssh/、lib/vquic/、lib/vdns/	TLS 后端、SSH 传输、QUIC、DNS 解析的可插拔适配层
include/curl/	libcurl 全部公开头文件（对外 API 的契约）
tests/	测试框架（runtests）、单元测试、lib 级测试与测试服务器
docs/	安装、依赖、手册页源文件等全部文档
CMake/、CMakeLists.txt、configure.ac	双构建系统（CMake 与 Autotools）配置
scripts/	构建辅助、代码风格检查、发布打包脚本

1.2 libcurl 的公开 API 头文件

include/curl/ 下的头文件即 libcurl 的完整对外接口面：

• include/curl/curl.h：核心头文件，Easy 接口（curl_easy_*）、版本常量、选项与信息枚举；
• include/curl/multi.h：Multi 接口（curl_multi_*），用于单线程驱动多个并发传输；
• include/curl/urlapi.h：URL API（curl_url_*），用于解析/构造 URL；
• include/curl/websockets.h：WebSocket 收发接口；
• include/curl/header.h：HTTP 头操作接口；
• include/curl/mprintf.h、include/curl/options.h 等辅助与选项定义。

对应实现可在 lib/easy.c、lib/multi.c、lib/urlapi.c、lib/ws.c 中找到；lib/cf-setup.c 等文件则体现了新版 libcurl 内部"过滤器（filter）"架构，传输管道各环节以过滤器串联。

二、支持的协议全集及源码落点

README 明确列出 curl 支持的协议：DICT、FILE、FTP、FTPS、GOPHER、GOPHERS、HTTP、HTTPS、IMAP、IMAPS、LDAP、LDAPS、MQTT、MQTTS、POP3、POP3S、RTSP、SCP、SFTP、SMB、SMBS、SMTP、SMTPS、TELNET、TFTP、WS 和 WSS。这些不是抽象声明，每个协议在 lib/ 下都有对应的实现文件：

协议	主要实现文件
HTTP / HTTPS	lib/http.c、lib/http1.c、lib/http2.c
FTP / FTPS	lib/ftp.c，TLS 经由 lib/vtls/
SMTP / SMTPS	lib/smtp.c、lib/pingpong.c（请求/应答同步模型）
POP3 / POP3S	lib/pop3.c
IMAP / IMAPS	lib/imap.c
MQTT / MQTTS	lib/mqtt.c
RTSP	lib/rtsp.c
TELNET	lib/telnet.c
TFTP	lib/tftp.c
DICT	lib/dict.c
GOPHER / GOPHERS	lib/gopher.c
FILE	lib/file.c
LDAP / LDAPS	lib/ldap.c、lib/openldap.c
SCP / SFTP	lib/vssh/（libssh / libssh2 后端适配）
SMB / SMBS	lib/smb.c
WS / WSS	lib/ws.c

协议不是不可裁剪的黑盒：CMakeLists.txt 中为每个协议提供了独立的编译开关，例如 CURL_DISABLE_FTP、CURL_DISABLE_SMTP、CURL_DISABLE_MQTT、CURL_DISABLE_WEBSOCKETS、CURL_DISABLE_TELNET、CURL_DISABLE_TFTP、CURL_ENABLE_SMB 等，且这些选项默认全部开启（OFF 表示"不禁用"）。此外还有一个总开关 HTTP_ONLY，开启后会强制禁用除 HTTP 外的所有协议，适合嵌入场景下裁剪二进制体积。

2.1 TLS 后端是可插拔的

HTTPS/FTPS/SMTPS 等安全变体依赖 TLS 后端。从 CMakeLists.txt 可以看到 libcurl 支持六类后端：

• OpenSSL（CURL_USE_OPENSSL，在未指定其他后端时默认开启）；
• Windows 原生 Schannel（CURL_USE_SCHANNEL，仅 WIN32）；
• mbedTLS（CURL_USE_MBEDTLS，要求 ≥ 3.2.0）；
• wolfSSL（CURL_USE_WOLFSSL）；
• GnuTLS（CURL_USE_GNUTLS，同时需要 Nettle）；
• rustls（CURL_USE_RUSTLS，标记为 experimental）。

具体后端实现放在 lib/vtls/ 下，各后端以独立源文件并列存放，由编译期选项选择其一或同时启用多个（多后端时置位 CURL_WITH_MULTI_SSL）。

三、安装与从源码构建

README 指出：普通用户通常下载二进制发行版；而本文档体系（以 docs/INSTALL.md 为代表）描述的是从源码编译、构建和安装的完整方法。以下流程以当前仓库结构为准。

3.1 Autotools 路径（Unix 三/四步法）

docs/INSTALL.md 给出的标准流程：

./configure --with-openssl [--with-gnutls --with-wolfssl]
make
make test        # 可选
make install     # 通常需要 root 权限

要点：

• 必须显式选择 TLS 后端，除非使用 --without-ssl 放弃 TLS；
• OpenSSL 不在默认搜索路径时，可借助 pkg-config 指定：env PKG_CONFIG_PATH=/opt/OpenSSL/lib/pkgconfig ./configure --with-openssl，或直接用 ./configure --with-openssl=/opt/OpenSSL；
• 自定义安装前缀可避免 root：./configure --prefix=$HOME && make && make install；
• 静态构建用 ./configure --disable-shared，但 docs/INSTALL.md 提醒："静态构建不是给心软的人准备的"（Building statically is not for the faint of heart），所有依赖库需要自行在链接命令行上补齐；
• 完整选项列表用 ./configure --help 查看；
• 默认会尝试启用 libpsl（公共后缀列表）支持，系统没有该库时用 --without-libpsl 关闭。

3.2 CMake 路径

CMakeLists.txt 要求 cmake_minimum_required(VERSION 3.18)。典型最小流程（选项名均出自 CMakeLists.txt）：

cmake -S . -B build -DCURL_USE_OPENSSL=ON
cmake --build build
cmake --install build        # 安装（前缀由 -DCMAKE_INSTALL_PREFIX 控制）

值得注意的构建选项：

选项	默认	说明
BUILD_CURL_EXE	ON	是否构建 curl 可执行文件
BUILD_SHARED_LIBS	按平台	构建共享库 libcurl
BUILD_STATIC_LIBS	OFF	构建静态库
BUILD_STATIC_CURL	OFF	让 curl 工具链接静态 libcurl
ENABLE_ARES	OFF	启用 c-ares 异步 DNS 解析
ENABLE_THREADED_RESOLVER	ON（启用 c-ares 时 OFF）	线程化 DNS 解析
HTTP_ONLY	OFF	只保留 HTTP 协议，覆盖所有 CURL_DISABLE_*
CURL_BUILD_EVERYTHING	OFF	默认构建示例与测试目标

CMake 侧还有 CMake/ 目录下的 Find*.cmake 模块（FindBrotli、FindLibssh2、FindMbedTLS 等）负责各可选依赖的发现逻辑，以及 CMake/FindGnuTLS.cmake 这类逐后端探测脚本。CMake 专项说明可继续阅读 docs/INSTALL-CMAKE.md。

3.3 直接从 Git 仓库构建

README 的 "Source code" 一节给出的入口就是克隆仓库（例如 git clone https://github.com/curl/curl）。若从 git 检出而非发布 tarball 构建，需要先再生成工具链文件，GIT-INFO.md 给出：

autoreconf -fi
./configure --with-openssl
make

docs/INSTALL.md 还提到 vcpkg 途径：vcpkg install curl[tool] 可同时获得库与命令行工具。部分特性（如生成 man 页）需要 Perl，pytest 测试套件需要 Python——这与 CMakeLists.txt 中 find_package(Perl) 后注册 curl-lint 等自定义目标的逻辑一致。

3.4 依赖版本基线

构建与运行时依赖的最低版本统一登记在 docs/DEPENDENCIES.md，摘录关键项：

依赖	最低版本	用途
OpenSSL	3.0.0	TLS（亦支持 LibreSSL 2.9.1、mbedTLS 3.2.0、wolfSSL 5.0.0、GnuTLS 3.6.5）
libssh2 / libssh	1.9.0 / 0.9.0	SFTP、SCP
nghttp2 / nghttp3 / ngtcp2	1.15.0 / 1.0.0 / 1.0.0	HTTP/2、HTTP/3
c-ares	1.16.0	异步 DNS
zlib / brotli / zstd	1.2.5.2 / 1.0.0 / 1.0	内容编码压缩
libpsl	0.16.0	Cookie 公共后缀匹配
Perl	5.8（Windows 5.22）	生成 man 页等构建工具
CMake / autoconf 系	3.18 / 2.59 等	构建工具链

该文档同时声明移植性目标：以 C89 编译器在 32 位及以上机器编译，编译器必须支持 64 位整型和 C99 风格的 stdint.h 定宽类型。

四、安全响应与许可

README 的 "Security problems" 一节要求：疑似安全问题必须私下报告，而非公开披露。仓库内的落地文件是 SECURITY.md，它指向 docs/VULN-DISCLOSURE-POLICY.md 的完整披露政策，并说明安全事件在受控且负责任地披露之前会保持机密；SECURITY.md 还记录了项目已获得的 OpenSSF Best Practices Gold 状态。

许可方面，README 声明 curl 为开源软件，采用 MIT 风格的 "curl" 许可证（SPDX 标识符 curl）。仓库中可直接查看 LICENSES/curl.txt 与 COPYING；REUSE.toml 按 REUSE 规范为无法直接加注的文件（如测试数据、项目模板）登记版权与许可证信息，保证每个文件的授权状态可机器核验。项目贡献者名单收录于 docs/THANKS，参与贡献的流程见 docs/CONTRIBUTE.md。

五、小结与延伸阅读

• 定位：curl 工具（src/）与 libcurl（lib/ + include/curl/）一体两面，覆盖 27 个协议标识、22 个独立协议实现文件；
• 构建：Autotools 与 CMake 双轨、功能基本对等；CMake 3.18+、显式选择 TLS 后端是两条路径的共同前提；git 检出需先 autoreconf -fi；
• 裁剪与扩展：CURL_DISABLE_* 系列选项 + HTTP_ONLY 支撑嵌入式裁剪，六选 N 的 TLS 后端支撑跨平台部署；
• 安全与合规：私有漏洞披露流程 + REUSE 许可标注，构成完整的信任链条。

进一步阅读建议：命令行手册页源文件 docs/cmdline-opts/MANPAGE.md 及各选项独立文档（如 docs/cmdline-opts/follow.md）、libcurl 手册页 docs/libcurl/、依赖清单 docs/DEPENDENCIES.md、CMake 安装指南 docs/INSTALL-CMAKE.md 与 git 构建说明 GIT-INFO.md。