如何通过CURLOPT_POSTFIELDS向cURL提交同键名多文件？

对接一个支持通过multipart form data单次HTTP POST接收多文件的API，所有文件的键名均为images。Postman及对应的cURL命令可正常执行：

curl --location 'http://my-amazing-service.local' \
--form 'images=@"/Users/zach/Desktop/1.jpg"' \
--form 'images=@"/Users/zach/Desktop/2.jpg"' \
--form 'images=@"/Users/zach/Desktop/3.jpg"'

但在PHP中使用CURLOPT_POSTFIELDS传递多维数组的写法，在Mac上能正常运行，到Alpine Linux的Docker容器中却失效——请求头中的Content-Length仅为146，说明约50KB的图片二进制内容未被正确包含。代码如下：

$curl = curl_init();
      
curl_setopt_array($curl, array(
    CURLOPT_URL => 'http://my-amazing-service.local',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_POSTFIELDS => [
        'images' => [
            file_get_contents('1.jpg'),
            file_get_contents('2.jpg'),
            file_get_contents('3.jpg'),
        ],
    ]
));
$verbose = fopen('php://temp', 'w+');
curl_setopt($curl, CURLOPT_STDERR, $verbose);
curl_setopt($curl, CURLOPT_VERBOSE, true);
$response = curl_exec($curl);
if ($response === FALSE) {
    printf("cURL error: %s\n", curl_error($curl));
}
rewind($verbose);
$verboseLog = stream_get_contents($verbose);
echo "Verbose information:\n<pre>", $verboseLog, "</pre>\n";        
curl_close($curl);    

请问是否可以在不手动编写原始multipart POST请求体的前提下，通过CURLOPT_POSTFIELDS传递多个同键名文件？

可以实现，核心是使用一维数组重复声明images键，同时每个文件值采用PHP cURL支持的标准文件上传格式（而非直接传递file_get_contents读取的内容）。

正确实现代码 #

PHP cURL处理multipart文件上传时，每个文件项需用CURLFile类（PHP 5.5+推荐）或指定文件路径的格式，针对同键名多文件，直接在一维数组中重复定义images键即可：

$curl = curl_init();

// 准备POST字段，重复使用images键
$postFields = [];
// 推荐方式：使用CURLFile类（安全且兼容规范）
$postFields['images'] = new CURLFile('1.jpg', 'image/jpeg', '1.jpg');
$postFields['images'] = new CURLFile('2.jpg', 'image/jpeg', '2.jpg');
$postFields['images'] = new CURLFile('3.jpg', 'image/jpeg', '3.jpg');

// 兼容旧版本方式：使用@前缀（需关闭CURLOPT_SAFE_UPLOAD，存在安全风险）
// curl_setopt($curl, CURLOPT_SAFE_UPLOAD, false);
// $postFields['images'] = '@' . realpath('1.jpg') . ';filename=1.jpg;type=image/jpeg';
// $postFields['images'] = '@' . realpath('2.jpg') . ';filename=2.jpg;type=image/jpeg';
// $postFields['images'] = '@' . realpath('3.jpg') . ';filename=3.jpg;type=image/jpeg';

curl_setopt_array($curl, [
    CURLOPT_URL => 'http://my-amazing-service.local',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_POSTFIELDS => $postFields,
]);

// 后续日志及执行逻辑保持不变
$verbose = fopen('php://temp', 'w+');
curl_setopt($curl, CURLOPT_STDERR, $verbose);
curl_setopt($curl, CURLOPT_VERBOSE, true);
$response = curl_exec($curl);
if ($response === FALSE) {
    printf("cURL error: %s\n", curl_error($curl));
}
rewind($verbose);
$verboseLog = stream_get_contents($verbose);
echo "Verbose information:\n<pre>", $verboseLog, "</pre>\n";        
curl_close($curl);

环境差异原因 #

Mac上的PHP/cURL版本可能对多维数组做了非规范兼容处理，而Alpine Linux容器中的环境严格遵循PHP官方规范——CURLOPT_POSTFIELDS的多维数组仅支持嵌套关联数组（用于子字段），不支持索引数组传递同键名多文件，因此直接解析失败，导致未携带文件内容。

关键注意事项 #

• 必须用一维数组重复声明目标键名，PHP cURL会自动将其处理为multipart form中的多个同键名字段。
• 优先使用CURLFile类，@前缀在PHP 5.6+默认被CURLOPT_SAFE_UPLOAD禁用，手动关闭存在安全风险。
• 容器环境中需确保文件路径正确，注意文件挂载或工作目录配置，避免出现文件找不到的情况。

内容的提问来源于stack exchange，提问作者Zach Rattner