php 5.6+ 必须用 curlfile 类上传文件，禁用 @ 语法，否则报致命错误；需显式指定 mime 类型和上传文件名，并通过 class_exists('curlfile') 判断兼容性。
PHP 5.5+ 的 CURLOPT_POSTFIELDS 文件上传语法必须改用 CURLFile
PHP 5.6 起已彻底移除 @/path/to/file 这种旧式写法，继续使用会直接报错：The usage of the @filename API for file uploading is deprecated. Please use the CURLFile class instead。这不是警告，是致命异常。
必须改用 CURLFile 实例，它还能显式指定 MIME 类型和文件名（避免服务端解析失败）：
if (class_exists('CURLFile')) {
$file = new CURLFile('/tmp/test.png', 'image/png', 'avatar.png');
curl_setopt($ch, CURLOPT_POSTFIELDS, ['file' => $file]);
} else {
// PHP '@/tmp/test.png']);
}
注意三点：
-
CURLFile构造函数第三个参数是「服务端看到的文件名」，不是本地路径，建议设为安全随机名（如uniqid().'.png'） - 若服务端依赖原始文件名做校验，这个参数就很重要；否则传空字符串也行，但不推荐
- 不要在
CURLFile第一个参数里加@，否则会当成字面量路径处理，导致couldn't open file错误码 26
curl_setopt($ch, CURLOPT_SAFE_UPLOAD) 在 PHP 5.5–5.6 间行为不一致
这个选项控制是否允许 @ 语法，但它在不同小版本中默认值不同，容易被忽略：
- PHP 5.5.0：默认
false（兼容旧写法），但会触发E_DEPRECATED警告 - PHP 5.6.0+：默认
true，且@语法被硬性禁用，curl_setopt会直接失败 - 手动设为
false在 5.6+ 无效，PHP 会忽略并抛出异常
所以别依赖这个开关，统一用 CURLFile + 版本判断是最稳方案。检查当前环境是否支持的最简方式：
var_dump(class_exists('CURLFile'));
上传成功但服务端收不到文件，可能是 CURLFile MIME 类型没配对
有些后端框架（如 Laravel、ThinkPHP）或 Nginx 配置会严格校验 Content-Type 字段。如果只传路径不指定 MIME，CURLFile 默认用 application/octet-stream，而服务端可能只接受 image/jpeg 或 image/png。
解决方法是显式传入 MIME 类型：
$mimeType = mime_content_type('/tmp/test.png'); // 或根据扩展名映射
$file = new CURLFile('/tmp/test.png', $mimeType, 'test.png');
常见陷阱：
-
mime_content_type()函数需启用fileinfo扩展，否则返回false - 不要硬编码
image/jpg—— 正确是image/jpeg，错一个字母服务端可能拒收 - 上传 PNG 却传
image/jpeg，某些校验严格的接口会直接 415
为什么本地能传、线上就失败？先确认 PHP 版本和 cURL 版本双匹配
仅看 php -v 不够。cURL 库本身也有版本差异，尤其在 HTTPS 证书验证、HTTP/2 支持上。执行以下两行命令比对：
php -r "echo CURL_VERSION_STRING;"
curl --version
典型问题：
- 服务器 cURL 版本太老（如 7.29），不支持 HTTP/2，而目标 API 强制要求
- PHP 编译时未链接 OpenSSL，导致 HTTPS 上传握手失败，错误日志里可能只有
SSL connect error，没有更细线索 - 开发机是 PHP 8.1 + cURL 7.81，线上是 PHP 7.4 + cURL 7.58 —— 表面版本够，但底层能力断层
这种差异不会报语法错误，但会导致连接中断、数据截断或服务端收不到完整 multipart body。最简单的验证方式：用 curl -v 命令行复现请求，观察响应头和 body 是否完整。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
