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 多维结构。

NNiji·Journey

二次元风格绘画生成器，由 Spellbrush 与 Midjourney 共同设计开发

下载

立即学习“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 缺陷。务实方案是显式索引或使用预处理器统一展开，既保证兼容性，又提升代码可维护性。