PHP Curl POST同时上传文件与数组参数报错问题求解

PHP cURL 扩展处理传入CURLOPT_POSTFIELDS的数组参数时，不会自动给数组类型字段追加[]后缀，直接传入嵌套数组时，cURL会尝试将数组值强制转换为字符串，触发Array to string conversion报错。
此前尝试的方案存在明确问题：

• 传入http_build_query处理后的参数，会将请求编码为application/x-www-form-urlencoded格式，破坏文件上传必需的multipart/form-data结构，导致文件MIME信息丢失，触发415 Unsupported Media Type错误
• 手动指定数组键名时重复使用colours[2]作为键，PHP数组中同键名的内容会被后写入的值覆盖，最终传递的参数结构不符合服务端数组要求

不需要构造重复键的数组，手动为数组类字段指定带不重复索引的键名即可，服务端会自动将符合字段名[索引]格式的参数解析为数组，和命令行curl的-F传参效果完全一致：

$url = 'https://the.url.com/upload';
$filePath = 'path/to/the/file'; // 替换为本地实际文件路径

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, [
    'file' => curl_file_create($filePath),
    'colours[0]' => 'red',
    'colours[1]' => 'yellow',
    'colours[2]' => 'blue'
]);

$response = curl_exec($ch);
// 如需排查错误可打开下一行注释
// $curlError = curl_error($ch);
curl_close($ch);

• curl_file_create会自动识别文件MIME类型，支持自定义二进制格式文件上传，无需手动指定类型
• 包含文件上传的参数禁止使用http_build_query处理，会直接破坏multipart编码结构，导致文件上传失败
• 数组字段的索引不需要连续，也不需要从0开始，只要括号内的标识不重复，主流服务端框架都会将其解析为对应名称的数组参数

内容的提问来源于stack exchange，提问作者Robin Fuller