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

PHP 中使用 cURL 上传多个文件时，若直接用 "file[]" => $curlfile 形式赋值，因数组键重复导致仅最后一个文件生效；需显式指定索引（如 "file[0]"、"file[1]"）或通过预处理函数自动展开文件数组。

php 中使用 curl 上传多个文件时，若直接用 `"file[]" => $curlfile` 形式赋值，因数组键重复导致仅最后一个文件生效；需显式指定索引（如 `"file[0]"`、`"file[1]"`）或通过预处理函数自动展开文件数组。

在命令行中，curl -F "file[]@file1.png" -F "file[]@file2.pdf" 能自然形成 $_FILES['file'] 的多维结构（含 name、tmp_name 等子数组），这是 curl 工具对重复字段名的原生支持。但 PHP 的 CURLOPT_POSTFIELDS 并不识别 [] 语法——当键名完全相同时（如两次 "file[]"），后赋值会覆盖前赋值，最终仅保留最后一个 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['file'] 将完整接收两个文件，结构与 shell curl 一致。

⚠️ 注意事项

• CURLFile 构造必须完整：路径需为服务器可读的绝对路径，mime 类型建议准确填写（可使用 mime_content_type() 推断），postname（即上传后的文件名）建议显式指定，避免默认使用本地路径名。
• PHP 版本兼容性：CURLFile 自 PHP 5.5.0 引入；若使用旧版本，请改用 @/path 语法（已弃用且不推荐）。
• 不要混用 @ 和 CURLFile：CURLOPT_POSTFIELDS 中同时存在 @ 字符串和 CURLFile 实例可能导致未定义行为，应统一使用 CURLFile。

? 进阶方案：自动展开文件数组（封装复用）

若需频繁上传动态数量的文件，可封装一个预处理器，将形如 'files' => [$f1, $f2, $f3] 的结构自动转为 'files[0]' => $f1, 'files[1]' => $f2, ...：

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

function expandFileArrays(array &$data): void {
    foreach ($data as $key => $value) {
        // 仅处理值为数组且至少含一个 CURLFile 的字段
        if (is_array($value) && !empty($value) && $value[0] instanceof CURLFile) {
            unset($data[$key]);
            foreach ($value as $index => $file) {
                $data[$key . '[' . $index . ']'] = $file;
            }
        }
    }
}

// 使用示例
$files = [
    new CURLFile('/tmp/report.pdf', 'application/pdf', 'report.pdf'),
    new CURLFile('/tmp/chart.png', 'image/png', 'chart.png'),
];

$data = [
    'g'     => 'GROUP',
    'o'     => 'object',
    'm'     => 'body.',
    'file'  => $files, // ← 统一用普通键名，无需 [] 后缀
];

expandFileArrays($data); // 自动转换为 file[0], file[1], ...

// 此时 $data 可直接传入 CURLOPT_POSTFIELDS

该函数轻量、无外部依赖，适用于批量上传场景，显著提升代码可读性与维护性。

✅ 总结

PHP cURL 不支持 shell 中 file[] 的“隐式数组”语法，根本原因在于 PHP 数组键名唯一性约束。没有“无需索引”的标准语法——所谓 file[] 在 PHP 数组中只是普通字符串键，重复即覆盖。因此，生产环境推荐两种实践：

• 简单场景：显式写 file[0]、file[1]；
• 复杂场景：封装 expandFileArrays() 等工具函数，实现语义清晰、扩展性强的多文件上传逻辑。