PHP cURL 多文件上传的正确姿势：解决 file[] 数组键名丢失问题

PHP 中使用 cURL 通过 CURLOPT_POSTFIELDS 上传多个文件时，若直接使用 “file[]” => $curlfile 形式会导致后一个文件覆盖前一个；必须显式指定索引（如 “file[0]”、”file[1]”）或借助预处理函数自动展开数组。

php 中使用 curl 通过 `curlopt_postfields` 上传多个文件时，若直接使用 `”file[]” => $curlfile` 形式会导致后一个文件覆盖前一个；必须显式指定索引（如 `”file[0]”`、`”file[1]”`）或借助预处理函数自动展开数组。

在 php 中通过 cURL 向服务端提交多文件（如邮件附件），常期望复现 Shell 中 curl -F “file[]@file1.png” -F “file[]@file2.pdf” 的行为——即服务端接收形如 $_FILES[‘file’][‘name’][0]、$_FILES[‘file’][‘name’][1] 的完整数组结构。然而，直接在 PHP 数组中重复使用相同键名 “file[]” 是无效的，因为 PHP 关联数组键名必须唯一，后赋值会覆盖前值：

// ❌ 错误：键名重复，$curlfile2 将覆盖 $curlfile1 $data = [     "g" => "GROUP",     "o" => "object",     "m" => "body.",     "file[]" => $curlfile1, // 被下一行覆盖     "file[]" => $curlfile2, // 实际仅保留此项 ];

这导致服务端 $_FILES[‘file’] 仅包含单个文件，与 Shell 命令行为不一致。

✅ 正确做法是显式指定数组索引，确保每个 CURLFile 对应独立键名：

$curlfile1 = new CURLFile('/path/to/file1.png', 'image/png', 'file1.png'); $curlfile2 = new CURLFile('/path/to/file2.pdf', 'application/pdf', 'file2.pdf');  $data = [     "g" => "GROUP",     "o" => "object",     "m" => "body.",     "file[0]" => $curlfile1,     "file[1]" => $curlfile2, ];  $ch = curl_init(); curl_setopt_array($ch, [     CURLOPT_URL => 'http://localhost/api/email.php',     CURLOPT_POST => true,     CURLOPT_POSTFIELDS => $data,     CURLOPT_RETURNTRANSFER => true,     CURLOPT_SSL_VERIFYPEER => false, ]); $response = curl_exec($ch); curl_close($ch);

此时服务端可正常解析为标准 $_FILES 多维结构。

立即学习“PHP免费学习笔记（深入）”；

? 若需动态处理任意数量文件并避免手动索引，可封装通用预处理器函数。该函数遍历数据数组，将值为数组的字段（如 “files” => [$f1, $f2, $f3]）自动转换为带索引的扁平键名（”files[0]”, “files[1]”, “files[2]”）：

function flattenFileArrays(array &$data): void {     $keysToProcess = [];     foreach ($data as $key => $value) {         if (is_array($value) && !empty($value) &&              array_keys($value) === range(0, count($value) - 1)) {             $keysToProcess[] = $key;         }     }      foreach ($keysToProcess as $key) {         $values = $data[$key];         unset($data[$key]);         foreach ($values as $index => $val) {             $data["{$key}[{$index}]"] = $val;         }     } }  // 使用示例 $files = [     new CURLFile('/tmp/report.pdf', 'application/pdf'),     new CURLFile('/tmp/chart.png', 'image/png'),     new CURLFile('/tmp/data.csv', 'text/csv') ];  $data = [     "g" => "GROUP",     "o" => "Report",     "m" => "Please find attached...",     "files" => $files, // 自动展开为 files[0], files[1], files[2] ];  flattenFileArrays($data); // 现在 $data 包含 'files[0]', 'files[1]', 'files[2]' 等键

⚠️ 注意事项：

• CURLFile 构造函数参数顺序为 (filename, mime_type, post_filename)，post_filename 可选但建议显式指定原始文件名，便于服务端识别；
• 确保 PHP 版本 ≥ 5.5.0（CURLFile 引入版本），并启用 curl 扩展；
• 不要混用 @ 语法（已废弃且禁用）与 CURLFile，后者是当前唯一安全可靠的文件上传方式；
• 服务端需按标准 $_FILES 结构解析，注意 Error 字段为 0 表示上传成功。

? 总结：PHP cURL 不支持 Shell 风格的 “key[]” 重复键名语法，这是语言层限制而非 cURL 缺陷。务实方案是显式索引或使用预处理器统一展开，既保证兼容性，又提升代码可维护性。