必须同时设置CURLOPT_CONNECTTIMEOUT（连接超时，建议5～10秒）和CURLOPT_TIMEOUT（总超时，应≥连接超时并预留传输时间），否则仅设其一易导致卡顿；上传大文件时还需配合CURLOPT_LOW_SPEED_LIMIT/TIME防假活，并禁用冗余进度回调以避免超时误判。
curl_easy_setopt设置CURLOPT_TIMEOUT和CURLOPT_CONNECTTIMEOUT
libcurl上传超时分两层：连接建立阶段和数据传输阶段。不区分设置，容易出现“卡住几十秒才失败”的情况。必须同时设 CURLOPT_CONNECTTIMEOUT（连接超时）和 CURLOPT_TIMEOUT（总超时），否则仅设其中一个效果有限。
常见错误是只设 CURLOPT_TIMEOUT，但服务器DNS解析慢或网络不通时，实际阻塞在 connect 阶段，而该阶段不受 CURLOPT_TIMEOUT 约束——它只管 connect 成功后的传输时间。
-
CURLOPT_CONNECTTIMEOUT单位是秒，建议设为 5～10，避免 DNS 或 SYN 重传拖太久 -
CURLOPT_TIMEOUT应 ≥CURLOPT_CONNECTTIMEOUT，且需预留上传大文件所需时间，比如上传 100MB 文件，按 1MB/s 估算至少要 100 秒，再加 buffer 设为 120 - 若需更精细控制（如单独限制上传阶段），可用
CURLOPT_LOW_SPEED_LIMIT+CURLOPT_LOW_SPEED_TIME防止“假活”连接
上传大文件时必须配合CURLOPT_NOPROGRESS和进度回调
默认启用进度回调会显著拖慢上传速度，尤其在高延迟网络下。libcurl 每发送约 1KB 就触发一次回调，若回调函数里有 I/O 或锁操作，极易导致超时误判。
真实场景中，用户常因启用了 CURLOPT_PROGRESSFUNCTION 却未设 CURLOPT_NOPROGRESS，结果上传卡在 99%、超时失败——其实不是网络问题，是回调开销压垮了定时器精度。
立即学习“C++免费学习笔记（深入）”；
基于5000余部现行法律法规进行的高质量专业合同审查，一键输出审查意见书，并附有参考法条原文，满足专业溯源核查要求。由accurLex知法提供技术支持。 Use when users ask for 合同审查, 审查意见书, 合同风险分析, 条款审查,知法,accurLex or 站在甲方/乙方角度审查合同 through accurLex direct API. China law only, plaintext only, review mode limited to 审查意见书.
- 禁用进度通知：调用
curl_easy_setopt(curl, CURLOPT_NOPROGRESS, 1L) - 如真需进度，确保回调函数极轻量（只更新内存变量，不 printf / log / GUI 刷新）
- 上传前用
curl_easy_setopt(curl, CURLOPT_UPLOAD, 1L)显式声明模式，避免 libcurl 自动降级为 POST
注意CURLOPT_TIMEOUT_MS等毫秒级选项的兼容性陷阱
CURLOPT_TIMEOUT_MS 和 CURLOPT_CONNECTTIMEOUT_MS 看似更精确，但它们在 libcurl
最稳妥的做法是统一用秒级选项 + 整数向下取整。例如你要 3.8 秒超时，就设 CURLOPT_CONNECTTIMEOUT 为 3，CURLOPT_TIMEOUT 为 4——别试图用 CURLOPT_TIMEOUT_MS 去凑小数。
- 检查运行时 libcurl 版本：
LIBCURL_VERSION_NUM宏值 ≥ 0x072000（即 7.32.0）才安全启用 _MS 后缀选项 - 设
CURLOPT_TIMEOUT_MS后务必检查curl_easy_perform()返回值，若返回CURLE_BAD_FUNCTION_ARGUMENT，说明当前库不支持 - 跨平台项目建议直接放弃 _MS 选项，用秒级 + 服务端重试逻辑兜底
超时不是万能的：TCP Keepalive 和 SSL 握手仍可能绕过
libcurl 的超时机制基于 select/poll/epoll 等系统调用，对已建立的 TCP 连接，在 SSL 握手卡死、服务端半关闭、中间设备静默丢包等场景下，CURLOPT_TIMEOUT 可能完全失效——连接看似活跃，实则 hang 住。
这时候需要操作系统级保活：启用 TCP keepalive，并缩短探测间隔。libcurl 不直接暴露 keepalive 参数，得通过 socket callback 手动 setsockopt。
- 注册 socket callback：
curl_easy_setopt(curl, CURLOPT_OPENSOCKETFUNCTION, opensocket_cb) - 在
opensocket_cb中对返回的 socket 调用setsockopt(fd, SOL_SOCKET, SO_KEEPALIVE, &optval, sizeof(optval)) - Linux 下还可追加
TCP_KEEPIDLE/TCP_KEEPINTVL控制首次探测和间隔（需内核 ≥ 2.4）
没做这一步，哪怕你设了 10 秒超时，遇到 TLS 1.3 early data 卡住或 NAT 设备老化连接，照样挂满 15 分钟才断。
