libcurl 是底层网络引擎，需手动管理资源；curl_easy_init() 必须配对 curl_easy_cleanup() 防泄漏；POST 数据超2GB时 CURLOPT_POSTFIELDS 失效；SSL 支持需先确认。
libcurl 不是开箱即用的“应用框架”，它是一个 C 语言编写的底层网络传输引擎，直接调用 libcurl 需要手动管理句柄、回调、错误和内存——没封装就别想写得快。
curl_easy_init() 后必须配对 curl_easy_cleanup()
这是最常被忽略的资源泄漏源头。每次 curl_easy_init() 返回一个 CURL* 句柄，它内部持有 DNS 缓存、SSL 上下文、连接池等资源。不调用 curl_easy_cleanup() 就退出，会导致：
- Linux/macOS 下 socket 文件描述符泄露，跑几次就 hit
Too many open files - Windows 下 HANDLE 泄漏，进程句柄数飙升
- SSL 证书缓存无法释放，重复请求可能复用过期会话
即使只发一次请求，也要写成：
struct curl_slist *headers = NULL;
CURL *curl = curl_easy_init();
if (curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://httpbin.org/get");
curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
curl_easy_perform(curl);
curl_easy_cleanup(curl); // 必须有
}
curl_slist_free_all(headers); // 同样不能漏
POST 数据体大小超过 2GB 时 CURLOPT_POSTFIELDS 失效
CURLOPT_POSTFIELDS 接收 void* 和 size_t，但某些旧版 libcurl（long 截断长度，导致超大 body 被截断或触发断言失败。
安全做法是改用 CURLOPT_READFUNCTION 流式上传：
size_t read_callback(void *ptr, size_t size, size_t nmemb, void *userp) {
FILE *fp = (FILE*)userp;
size_t len = fread(ptr, size, nmemb, fp);
if (len == 0 && feof(fp)) return 0;
return len;
}
// 使用时：
FILE *fp = fopen("bigfile.bin", "rb");
curl_easy_setopt(curl, CURLOPT_UPLOAD, 1L);
curl_easy_setopt(curl, CURLOPT_READFUNCTION, read_callback);
curl_easy_setopt(curl, CURLOPT_READDATA, fp);
curl_easy_setopt(curl, CURLOPT_INFILESIZE_LARGE, (curl_off_t)file_size);
-
CURLOPT_INFILESIZE_LARGE必须设为curl_off_t类型，不能用CURLOPT_INFILESIZE -
fread返回值需原样返回，libcurl 不做二次校验 - 文件指针
fp生命周期必须覆盖整个传输过程
多线程环境下 CURLOPT_NOSIGNAL 必须设为 1L
libcurl 默认启用 alarm() 和 siglongjmp() 实现超时控制，在多线程程序中（尤其是使用 glibc 的 Linux），这会干扰主线程信号处理，引发随机 crash 或 hang。
正确做法是在每个 CURL* 句柄上显式禁用：
curl_easy_setopt(curl, CURLOPT_NOSIGNAL, 1L);
- 该选项不影响超时功能本身，libcurl 会退回到 select()/poll() 轮询实现
- 若同时用
curl_multi_*接口，还需确保所有线程共享的CURLM*句柄也满足此要求（multi 接口默认已规避 signal） - macOS 上虽不报错，但
siglongjmp可能破坏 Objective-C ARC 栈帧，导致野指针
SSL 证书验证失败时 CURLOPT_SSL_VERIFYPEER=0L 不是解法
关掉证书验证（CURLOPT_SSL_VERIFYPEER, 0L）只是掩盖问题，且会让中间人攻击畅通无阻。真实场景应：
- 用
CURLOPT_CAINFO指向系统可信根证书路径（如 Linux 的/etc/ssl/certs/ca-bundle.crt） - 或用
CURLOPT_CAPATH指向目录（需先用c_rehash建索引） - 若服务端用私有 CA，把对应 PEM 文件路径传给
CURLOPT_CAINFO
调试阶段可加 CURLOPT_VERBOSE, 1L 查看握手细节，常见失败原因包括：
- 服务器证书域名不匹配（CN 或 SAN 不含请求 Host）
- 证书链不全（Nginx/Apache 未配置 fullchain.pem）
- 系统时间错误（证书有效期校验失败）
跨平台打包时，别硬编码证书路径；用 curl_version_info(CURLVERSION_NOW)->features & CURL_VERSION_SSL 先确认 SSL 支持可用，再决定是否加载证书。
