curl/libcurl 编译期裁剪宏全解析CURL_DISABLE_* 协议与功能开关使用指南【免费下载链接】curlA command line tool and library for transferring data with URL syntax, supporting 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 and WSS. libcurl offers a myriad of powerful features项目地址: https://gitcode.com/GitHub_Trending/cu/curl导读在嵌入式、容器或HTTP-only等受限场景中完整的 libcurl 常常显得过于庞大。本指南以仓库权威清单 docs/CURL-DISABLE.md 为主线系统梳理 curl 为开发者提供的全部CURL_DISABLE_*编译期开关——它们如何定义、如何传入构建系统、如何作用到源码以及各开关的精确语义与级联依赖关系。读完你不仅能按需裁剪出最小化的 curl/libcurl还能理解裁剪宏在 CMakeLists.txt、configure.ac 与 lib/curl_setup.h 之间的完整落地链路。一、什么是CURL_DISABLE_*面向特定场景的编译期裁剪libcurl 支持十余种应用层协议与大量扩展特性但并非每个部署都需要全部功能。curl 采用编译期条件编译方案通过一组形如CURL_DISABLE_XXX的预处理宏让开发者在编译阶段就剪掉用不到的协议与特性从而缩小可执行文件与库的体积减小攻击面与第三方依赖数量例如裁剪 FTP/TELNET 等不需要的协议规避特定平台编译问题例如 UWP 下强制禁用 Telnet加快构建与测试例如禁用curl_easy_setopt()类型检查。仓库根目录的 docs/CURL-DISABLE.md 是一份精炼的宏清单共收录46 个CURL_DISABLE_*宏外加 1 个反向宏CURL_ENABLE_SMBSMB 协议默认不编译需要显式打开。这些宏可归纳为四大类类别覆盖内容协议开关DICT、FILE、FTP(S)、GOPHER、HTTP(S)、IMAP(S)、LDAP(S)、MQTT、POP3、RTSP、SMTP(S)、TELNET、TFTP、WS(WSS)、IPFS/IPNS、SMB(S)HTTP 特性Alt-Svc、Cookie、DoH、HSTS、Headers API、MIME、Form API、HTTP 代理认证与签名Basic、Bearer、Digest、Kerberos、Negotiate、HTTP Auth 总开关、AWS sigv4、RFC 9421 HTTP Message Signatures内部机制与工具本地绑定、netrc、日期解析、进度条、代理、DNS 洗牌、socketpair、类型检查、verbose 字符串等下文将逐一给出每个宏的精确语义并说明其在源码与构建系统中的实现位置。二、宏是如何生效的从构建选项到条件编译的三层链路CURL_DISABLE_*并不是散落在源码里的临时#define它们遵循固定的定义—传递—生效链路。理解这条链路是正确使用裁剪开关的前提。2.1 第 1 层构建系统把它转成配置头文件以 CMake 为例根目录 CMakeLists.txt 为绝大多数开关声明了同名的option()CMake 布尔缓存变量例如option(CURL_DISABLE_FTP Disable FTP OFF) option(CURL_DISABLE_DICT Disable DICT OFF) option(CURL_DISABLE_PROXY Disable support for proxies OFF) option(CURL_ENABLE_SMB Enable SMB OFF)随后这些选项通过 lib/curl_config-cmake.h.in 中的#cmakedefine模板被渲染进生成的配置头文件#cmakedefine CURL_DISABLE_ALTSVC 1 #cmakedefine CURL_DISABLE_COOKIES 1 #cmakedefine CURL_DISABLE_FTP 1 ... #cmakedefine CURL_ENABLE_SMB 1在 autotools 构建体系configure.ac中逻辑等价./configure的各--disable-xxx选项内部执行AC_DEFINE(CURL_DISABLE_XXX, 1, ...)最终同样汇入生成的curl_config.h。2.2 第 2 层curl_setup.h统一引入库源码的第一道门槛是 lib/curl_setup.h它在第 140 行统一#include curl_config.h从而把构建期决定的全部CURL_DISABLE_*宏带入每个编译单元。因此用户通常不需要在源码里手动定义这些宏——只需在 CMake/configure 层面给出选项。2.3 第 3 层源码以#ifndef CURL_DISABLE_XXX守卫特性各特性实现文件中用条件编译将代码整体包裹。最典型的是 lib/cookie.c#if !defined(CURL_DISABLE_HTTP) !defined(CURL_DISABLE_COOKIES) ... #endif /* CURL_DISABLE_HTTP || CURL_DISABLE_COOKIES */同理lib/smb.c 用#if defined(CURL_ENABLE_SMB) defined(USE_CURL_NTLM_CORE)包裹lib/protocol.c 只在宏同时满足时才把 SMB handler 注册进协议表。curl 工具层src/同样按宏裁剪选项表与信息输出例如 src/config2setopts.c 用#ifndef CURL_DISABLE_IPFS包裹 IPFS 选项src/curlinfo.c 分别用CURL_DISABLE_HTTPSIG、CURL_DISABLE_HTTP_AUTH、CURL_DISABLE_VERBOSE_STRINGS、CURL_DISABLE_LIBCURL_OPTION裁剪对应的特性信息。提示所有 CMake 开关默认均为OFF不裁剪mark_as_advanced()表明它们是高级选项正常cmake交互界面不展示需显式通过-D传入。三、协议级开关精确到每种 URL scheme3.1 关闭型协议宏一览文档第一大类是协议裁剪绝大多数协议默认编译、用宏关掉宏文档语义补充说明源码依据CURL_DISABLE_DICT禁用 DICT 协议—CURL_DISABLE_FILE禁用 FILE 协议—CURL_DISABLE_FTP禁用 FTP连同 FTPS协议—CURL_DISABLE_GOPHER禁用 GOPHER 协议—CURL_DISABLE_HTTP禁用 HTTP(S) 协议副作用同时禁用 HTTP 代理支持见文档原句CURL_DISABLE_IMAP禁用 IMAP(S) 协议—CURL_DISABLE_LDAP禁用 LDAP(S) 协议LDAP 与 LDAPS 联动见 3.3CURL_DISABLE_LDAPS单独禁用 LDAPS 协议—CURL_DISABLE_MQTT禁用 MQTT 支持—CURL_DISABLE_POP3禁用 POP3 协议—CURL_DISABLE_RTSP禁用 RTSP 协议依赖 HTTP禁用 HTTP 后会被联动关闭CURL_DISABLE_SMTP禁用 SMTP(S) 协议—CURL_DISABLE_TELNET禁用 TELNET 协议UWP 构建强制启用该开关CURL_DISABLE_TFTP禁用 TFTP 协议—CURL_DISABLE_WEBSOCKETS禁用 WebSocket 协议无 HTTP 时无法成立会被联动关闭CURL_DISABLE_IPFS禁用 IPFS/IPNS只影响 curl 工具库中无此协议实现3.2 唯一的使能型宏CURL_ENABLE_SMB与其它宏不同SMB 需要的是打开而非关闭因此宏名是正向的CURL_ENABLE_SMB同时可在 lib/curl_config-cmake.h.in 中看到#cmakedefine CURL_ENABLE_SMB 1。文档原句为 Enable the SMB(S) protocols。从源码看它还有第二个前提条件lib/smb.c、lib/smb.h 与 lib/protocol.c 均要求CURL_ENABLE_SMB与USE_CURL_NTLM_CORE同时成立——即要启用 SMB(S)构建必须同时带 NTLM 支持。因此仅-DCURL_ENABLE_SMBON而底层无 NTLM 核心时协议仍不会被注册。3.3 协议裁剪的级联规则在curl_setup.h强制执行仅仅让各源码文件自行#ifndef还不够。curl 在 lib/curl_setup.h 中内置了两组兜底级联规则即使构建系统没有显式下发相关宏也会自动补齐HTTP_ONLY仅保留 HTTP当定义了HTTP_ONLYCMake 侧对应 CMakeLists.txt 的同名选项注释明确写着 overrides all CURL_DISABLE_* options会依次强制补上 DICT、FILE、FTP、GOPHER、IMAP、LDAP、LDAPS、MQTT、POP3、RTSP、SMTP、TELNET、TFTP、WEBSOCKETS 的禁用宏见 lib/curl_setup.hCURL_DISABLE_HTTPHTTP 一旦被禁用所有依赖 HTTP 的纯 HTTP 特性都会失去意义因此 lib/curl_setup.h 会顺带强制禁用 ALTSVC、AWS、BASIC_AUTH、BEARER_AUTH、COOKIES、DOH、FORM_API、HEADERS_API、HSTS、HTTPSIG、HTTP_AUTH、RTSP、WEBSOCKETS并注释 no WebSockets without HTTP present。CMake 顶层同样实现了这一级联CMakeLists.txt 在CURL_DISABLE_HTTP为真时把 ALTSVC/HSTS/IPFS/RTSP/WEBSOCKETS 一并置 ON。四、HTTP 相关特性开关这批宏针对的是HTTP 之上的扩展能力各自独立可裁宏文档语义影响面与实现CURL_DISABLE_ALTSVC禁用 Alt-Svc: HTTP 头支持即Alt-Svc头部与 alt-svc 缓存机制CURL_DISABLE_COOKIES禁用 HTTP Cookielib/cookie.c 整文件被!CURL_DISABLE_HTTP !CURL_DISABLE_COOKIES守卫CURL_DISABLE_DOH禁用 DNS-over-HTTPS影响CURLOPT_DOH_URL一类 DoH 功能CURL_DISABLE_HSTS禁用 HTTP Strict Transport Security影响 HSTS 缓存与CURLOPT_HSTS系列选项CURL_DISABLE_HEADERS_API禁用 HTTP 头 API即curl_easy_header()/curl_easy_nextheader()等 headers APICURL_DISABLE_MIME禁用 MIME 支持见下方 Form API 的依赖关系CURL_DISABLE_FORM_API禁用 form APICMake 中通过cmake_dependent_option声明FORM_API仅在NOT CURL_DISABLE_MIME时可选CMakeLists.txt因为表单构建于 MIME 之上注意 docs/CURL-DISABLE.md 与 lib/curl_setup.h 对CURL_DISABLE_HTTP的说明一致禁用 HTTP 的同时会连带禁用 HTTP 代理支持这点在设计纯非 HTTP 客户端时尤其值得留意。五、认证与消息签名开关认证体系被拆成粒度更细的开关既可逐个关闭特定认证类型也可用总开关一刀切宏文档语义说明CURL_DISABLE_BASIC_AUTH禁用 Basic 认证—CURL_DISABLE_BEARER_AUTH禁用 Bearer 认证—CURL_DISABLE_DIGEST_AUTH禁用 Digest 认证—CURL_DISABLE_KERBEROS_AUTH禁用 Kerberos 认证—CURL_DISABLE_NEGOTIATE_AUTH禁用 Negotiate(SPNEGO) 认证—CURL_DISABLE_HTTP_AUTH禁用全部HTTP 认证方法相当于上述认证开关的总闸门CURL_DISABLE_AWS禁用 aws-sigv4 支持AWS Signature Version 4 请求签名CURL_DISABLE_HTTPSIG禁用 RFC 9421 HTTP Message Signatures实验性特性CMake 侧该 option 的默认值为ON即构建系统默认不编译需要时显式置OFF从 configure 侧可印证这一分层的合理性configure.ac 对 Basic、Bearer、Digest、Kerberos、Negotiate、AWS、Cookies 等分别有独立的AC_DEFINE分支如CURL_DISABLE_BASIC_AUTH、CURL_DISABLE_HTTPSIG等说明各认证实现是相互独立的编译单元裁剪粒度可以做到认证类型级。六、内部机制、平台与工具侧开关6.1 库libcurl内部机制宏文档语义关键点CURL_DISABLE_BINDLOCAL禁用绑定连接本地端能力影响CURLOPT_INTERFACE相关绑定逻辑CURL_DISABLE_NETRC禁用 netrc 解析器影响CURLOPT_NETRC与--netrcCURL_DISABLE_PARSEDATE禁用日期解析影响curl_getdate()及 HTTP 日期头解析等CURL_DISABLE_PROGRESS_METER禁用内置进度条面向无终端/无交互场景CURL_DISABLE_PROXY禁用代理支持大幅裁剪CURLOPT_PROXY系列代码CURL_DISABLE_SHUFFLE_DNS禁用 DNS 洗牌shuffle特性影响CURLOPT_DNS_SHUFFLE_ADDRESSESCURL_DISABLE_SHA512_256禁用 SHA-512/256 哈希算法影响该哈希的专用实现路径CURL_DISABLE_SOCKETPAIR禁用内部socketpair()用法文档明确指出其用途禁用后无法依赖 socketpair 来唤醒与取消curl_multi_poll()CURL_DISABLE_OPENSSL_AUTO_LOAD_CONFIG禁用 OpenSSL 后端自动加载配置仅影响使用 OpenSSL 作为 TLS 后端时的行为CURL_DISABLE_GETOPTIONS禁用curl_easy_options()API该 API 让程序枚举curl_easy_setopt()的现有选项配合curl_easy_option_by_name()等CURL_DISABLE_TYPECHECK禁用curl_easy_setopt()/curl_easy_getinfo()类型检查仅影响编译期类型安全校验不改变运行时行为CURL_DISABLE_VERBOSE_STRINGS禁用 verbose 字符串与错误消息文本主要影响日志与错误提示字符串表CURL_DISABLE_CA_SEARCH禁用 Windows 上在 PATH 中搜索 CA bundle 的不安全行为平台特有Windows配套的正向宏CURL_CA_SEARCH_SAFE代表仅在工具目录内安全搜索CURL_DISABLE_LIBCURL_OPTION禁用 curl 工具的--libcurl选项该选项生成等价 C 源码纯工具侧功能6.2 值得展开的三点CURL_DISABLE_TYPECHECK与测试构建加速。文档特别说明它有助于提升tests/libtest测试工具的构建性能。CMake 侧的实现可见 CMakeLists.txt通过set_property(DIRECTORY ... COMPILE_DEFINITIONS ...)把该宏注入到整个目录含示例代码configure 侧则直接向CPPFLAGS追加-DCURL_DISABLE_TYPECHECK见 configure.ac。也就是说这只是牺牲编译期传参类型错误的静态检查来换取更快的编译适合跑测试套件而非发布。CURL_DISABLE_IPFS是纯工具开关。由于 IPFS/IPNS 的协议转换发生在 curl 命令行工具层src/config2setopts.c 附近用宏守卫相关选项libcurl 库本身不含 IPFS 协议所以该宏对库构建无影响。Windows 的CURL_DISABLE_CA_SEARCH。对应文件 lib/curl_config-cmake.h.in 同时定义了互斥的CURL_CA_SEARCH_SAFE前者是关闭在 PATH 环境变量中的不安全 CA 搜索后者代表只在 curl 工具自身目录内安全搜索是面向 Windows 证书查找安全的成对开关。七、裁剪的实际操作命令与组合建议7.1 CMake 方式# 仅裁剪个别协议 cmake -B build -DCURL_DISABLE_FTPON -DCURL_DISABLE_TFTPON -DCURL_DISABLE_DICTON # 只保留 HTTP等价于逐个关掉全部非 HTTP 协议 cmake -B build -DHTTP_ONLYON # 需要 SMB 时同时要求 NTLM core 可用 cmake -B build -DCURL_ENABLE_SMBON # 面向测试加速 cmake -B build -DCURL_DISABLE_TYPECHECKON注意HTTP_ONLY的 CMake 注释明确它是总开关会覆盖所有CURL_DISABLE_*选项CMakeLists.txt所以不要期望在HTTP_ONLYON的同时单独启用某个被排除的协议。7.2 autotoolsconfigure方式configure 体系为绝大多数裁剪宏提供了对应的--disable-xxx选项。在嵌入式裁剪场景下docs/INSTALL.md 给出了一整套建议尽量把用不到的--disable-/--without-选项全部显式列出为每个应用不需要的 URL 类型关闭对应协议。例如--disable-basic-auth、--disable-bearer-auth、--disable-digest-auth、--disable-http-auth、--disable-kerberos-auth、--disable-negotiate-auth、--disable-aws等认证类裁剪都在该文档的推荐清单中。具体到当前配置可用./configure --help查看全部可用开关。7.3 直接传编译器宏跨环境场景部分交叉编译环境受限于工具链无法运行 configure 的各类 disable 分支docs/INSTALL.md 对此有说明。此时可绕过构建选项直接向编译器传入预定义宏# 例如在已有构建配置基础上额外裁剪 Cookie 与 HSTS CFLAGS-DCURL_DISABLE_COOKIES -DCURL_DISABLE_HSTS ./configure ...但请记住两级生效规则特性代码自身的#ifndef CURL_DISABLE_XXX守卫决定这段代码编不编与curl_setup.h中的级联补全决定相关宏是否被自动补齐共同工作。直接传宏时级联补全依然会在 lib/curl_setup.h 生效因此依赖关系不会被破坏。7.4 验证裁剪结果构建完成后可运行curl -V版本输出会列出编译进去的协议与特性或在程序中调用curl_version_info()检查。注意 curl 工具的-V反映的是它链接的那份 libcurl 与自身实际编译进来的能力若某个协议被裁掉对应 scheme 将无法使用例如curl ftp://...会直接失败这正是定位裁剪是否生效的最快手段。八、使用裁剪宏的五条经验法则先看级联再单独关CURL_DISABLE_HTTP、HTTP_ONLY会连带关闭一批依赖特性lib/curl_setup.h别在关闭 HTTP 后又困惑于为什么 Cookie/DoH 也没了。区分库开关与工具开关CURL_DISABLE_IPFS、CURL_DISABLE_LIBCURL_OPTION只作用于 curl 工具src/其余绝大多数宏同时作用于 libcurl 与工具。留意反向宏与联动条件SMB 是靠CURL_ENABLE_SMB打开且必须配 NTLM corelib/smb.cLDAPS 与 LDAP 在 CMake 中默认联动CURL_DISABLE_LDAPS默认值跟随CURL_DISABLE_LDAPForm API 依赖 MIME 未被禁用CMakeLists.txt。CURL_DISABLE_HTTP还意味着失去 HTTP 代理若应用走 HTTP 代理上网误关 HTTP 会同时废掉代理通路。平台差异要单独处理CURL_DISABLE_CA_SEARCH仅针对 Windows 的 PATH CA 搜索UWP 构建会强制置上CURL_DISABLE_TELNETCMakeLists.txt。九、结语以文档为索引以源码为佐证本文所有宏的官方语义均来自仓库清单 docs/CURL-DISABLE.md而生效机制、级联规则与额外前提条件则可分别在上游构建文件 CMakeLists.txt、lib/curl_config-cmake.h.in、configure.ac、统一定义入口 lib/curl_setup.h 及各特性源文件如 lib/cookie.c、lib/smb.c、lib/protocol.c、src/config2setopts.c中逐一核实。当需要进一步阅读嵌入式最小化裁剪的完整选项清单时docs/INSTALL.md 中的 disable 选项列表是最佳延伸资料。【免费下载链接】curlA command line tool and library for transferring data with URL syntax, supporting 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 and WSS. libcurl offers a myriad of powerful features项目地址: https://gitcode.com/GitHub_Trending/cu/curl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考