CURLOPT_POSTFIELDS不能上传文件，仅支持文本或二进制内存数据；上传文件须用CURLOPT_UPLOAD+CURLOPT_READFUNCTION+CURLOPT_INFILESIZE组合，或CURLOPT_HTTPPOST构建multipart表单。
CURLOPT_POSTFIELDS 不能直接上传文件
这是最常被误解的一点：CURLOPT_POSTFIELDS 只接受纯文本或二进制内存数据，**不支持文件路径字符串自动读取上传**。如果你传入 "@/path/to/file" 这类写法（PHP 风格），libcurl 会原样发送这串字符，而不是读取文件内容——服务端收不到真实文件。
真正上传文件要用 CURLOPT_READFUNCTION + CURLOPT_INFILESIZE
libcurl 的文件上传依赖流式读取机制：你得自己打开文件、告诉 curl 数据长度、并提供一个回调函数供它按需读取数据块。核心组合是：
-
CURLOPT_UPLOAD设为1L（启用上传模式，不是 POST） -
CURLOPT_READFUNCTION指向你的读取回调函数 -
CURLOPT_INFILESIZE显式设置文件总字节数（避免 curl 调用fseek探测大小） -
CURLOPT_URL必须是接收上传的 endpoint（如https://example.com/upload），且协议要匹配（HTTP/HTTPS）
示例片段（省略错误检查）：
FILE *fp = fopen("image.jpg", "rb");
if (!fp) { /* handle error */ }
<p>curl_easy_setopt(curl, CURLOPT_URL, "<a href="https://www.php.cn/link/f142c6067e6345134c6728f299cf4c1e">https://www.php.cn/link/f142c6067e6345134c6728f299cf4c1e</a>");
curl_easy_setopt(curl, CURLOPT_UPLOAD, 1L);
curl_easy_setopt(curl, CURLOPT_READFUNCTION, [](char <em>ptr, size_t size, size_t nmemb, void </em>userdata) -> size_t {
FILE <em>f = static_cast<FILE</em>>(userdata);
size_t to_read = size * nmemb;
return fread(ptr, 1, to_read, f);
});
curl_easy_setopt(curl, CURLOPT_READDATA, fp);
curl_easy_setopt(curl, CURLOPT_INFILESIZE, 102400L); // 必须准确！
如果非要走 HTTP POST 表单上传（multipart/form-data）
那得用 CURLOPT_HTTPPOST，而不是 CURLOPT_POSTFIELDS。这是上传文件的「标准方式」，curl 会自动构造 multipart boundary 和头字段：
立即学习“C++免费学习笔记（深入）”；
利用农业相机拍摄植物叶片高分辨率图像，通过AI视觉技术检测叶片卷曲方向（向上卷曲或向下卷曲）
- 构建
curl_httppost链表，每个节点调用curl_formadd() - 字段名、文件路径、可选文件名（
filename）、内容类型（contenttype）都通过参数传入 - 最终把链表指针传给
CURLOPT_HTTPPOST，curl 自动处理编码和边界
关键点：CURLOPT_POSTFIELDS 在这里完全不用碰；误用会导致 multipart 被破坏或文件内容被当作文本发送。
容易忽略的细节：文件句柄生命周期和 INFILESIZE 准确性
回调函数里读取的 FILE* 必须在整个传输完成前保持有效——别在 curl_easy_perform() 前 fclose()；否则读取失败返回 0，curl 会提前终止上传。
CURLOPT_INFILESIZE 值必须与实际文件字节数一致。如果填小了，curl 可能只发一部分；填大了，回调读到 EOF 后返回 0，curl 会报 CURLE_SEND_ERROR 或挂起。建议用 fseek(fp, 0, SEEK_END); size = ftell(fp); fseek(fp, 0, SEEK_SET); 获取精确大小。
multipart 方式下，curl_formadd() 内部会自己探测文件大小，但依然要求文件在传输全程可读。
