正确做法是不手动设置Content-Type，让cURL自动构造multipart/form-data边界；文件字段须用CURLFile显式封装，普通字段保持数组键值对，禁用已废弃的@/path语法。
用 curl_setopt 正确设置 multipart/form-data 请求头
PHP 默认的 curl_setopt($ch, CURLOPT_POSTFIELDS, $data) 在传数组时会自动设为 multipart/form-data，但前提是 $data 必须是关联数组且**不显式设置 Content-Type 请求头**。一旦手动加了 Content-Type: application/x-www-form-urlencoded 或其他值，cURL 就会退化为 URL 编码提交，文件字段直接变成字符串（比如 Array 或路径名），后端收不到真实文件。
正确做法是：不设 Content-Type，让 cURL 自动构造边界（boundary）和 multipart 头；若必须控制 header，只设 Accept、User-Agent 等，把 Content-Type 交给 cURL 自己处理。
- 错误写法：
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: multipart/form-data; boundary=xxx'])—— 手动 boundary 极难同步，且 PHP 不会帮你填 body - 正确写法：
curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data)，其中$post_data是含['file' => new CURLFile('/path/to/file.jpg'), 'name' => 'test']的数组 -
CURLFile构造时路径必须真实存在，否则 curl 返回空或 0 字节文件
混合传参时区分文件与普通字段的写法
表单里既有文本字段（如 title、id），又有文件（如 avatar、report.pdf），不能把所有字段塞进一个字符串拼接的 POST body 里 —— 那样文件内容会被当纯文本发过去，后端 $_FILES 为空。
必须用 CURLFile 显式包装每个文件字段，其余字段保持原样作为数组键值对：
立即学习“PHP免费学习笔记（深入）”；
$post_data = [
'title' => '测试上传',
'category' => 'image',
'avatar' => new CURLFile('/tmp/photo.png', 'image/png', 'photo.png'),
'report' => new CURLFile('/tmp/log.pdf', 'application/pdf', 'log.pdf')
];
- 第三个参数（
postname）是文件在表单中显示的原始文件名，影响$_FILES['avatar']['name']，建议和磁盘文件名一致 - 第二个参数（
mimetype）非强制，但某些后端校验 MIME 类型，填错会导致拒绝接收（如传text/plain却发 png 数据） - 不要用
@/path语法（已废弃且在 PHP 7.4+ 报 Warning）
绕过 CURLFile 兼容性问题的备选方案
部分旧环境（如 PHP CURLFile，或某些 Docker 容器里 cURL 编译时没开 --enable-http 导致 multipart 失效。此时可手动生成 boundary 和 raw body，但代价是代码变复杂、易出错。
核心逻辑：生成唯一 boundary 字符串 → 拼接每段字段（区分 file/text）→ 设置 Content-Type 为 multipart/form-data; boundary=xxx → 用 curl_setopt($ch, CURLOPT_POSTFIELDS, $raw_body) 发送。
- boundary 必须不含引号、空格、下划线以外的特殊字符，推荐用
'----'.uniqid() - 文件段结尾需带
\r\n，最后一段后要加--boundary--\r\n - 文本字段的
Content-Disposition不带filename，文件字段必须带 - 此方式无法享受 cURL 内置的文件流式上传，大文件容易内存溢出
调试时快速验证是否真传了文件
后端收不到 $_FILES？先确认请求发出去的是不是 multipart。最简单的方法是用 curl -v 对比：
✅ 正常 multipart 请求的 Content-Type 头类似：Content-Type: multipart/form-data; boundary=------------------------d1a2b3c4e5f6g7h8
❌ 错误情况：Content-Type: application/x-www-form-urlencoded 或压根没 Content-Type 头（此时 cURL 默认用 urlencoded）
- 在 PHP 中加
curl_setopt($ch, CURLOPT_VERBOSE, true)并重定向STDERR，能看到完整请求头和前几行 body - 用
tcpdump或mitmproxy抓包，看实际发出的 body 是否含filename=和二进制数据块 - 如果后端是自己写的，打印
getallheaders()和file_get_contents('php://input')，确认原始输入结构
multipart 的边界和字段分隔非常敏感，少一个换行、多一个空格都会导致整个 body 解析失败 —— 这类细节在调试日志里往往一闪而过，得盯住 raw bytes 看。
