考虑 PHP 5.0~5.6 各版本兼容性的 cURL 文件上传

最新推荐文章于 2025-05-31 22:56:14 发布

最新推荐文章于 2025-05-31 22:56:14 发布 · 699 阅读

本文介绍了使用PHP通过cURL以multipart/form-data格式上传文件的方法。针对不同PHP版本间的差异进行了探讨，并提供了兼容5.4及5.6版本的代码实现方案。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

最近做的一个需求，要通过PHP调用cURL，以multipart/form-data格式上传文件。踩坑若干，够一篇文章了。

重要警告

没事不要读PHP的官方中文文档！版本跟不上坑死你！

不同版本PHP之间cURL的区别

PHP的cURL支持通过给CURL_POSTFIELDS传递关联数组（而不是字符串）来生成multipart/form-data的POST请求。

传统上，PHP的cURL支持通过在数组数据中，使用“@+文件全路径”的语法附加文件，供cURL读取上传。这与命令行直接调用cURL程序的语法是一致的：

curl_setopt(ch, CURLOPT_POSTFIELDS, array(
    'file' => '@'.realpath('image.png'), 
)); 
equals
$ curl -F "file=@/absolute/path/to/image.png" <url>

但PHP从5.5开始引入了新的CURLFile类用来指向文件。CURLFile类也可以详细定义MIME类型、文件名等可能出现在multipart/form-data数据中的附加信息。PHP推荐使用CURLFile替代旧的@语法：

curl_setopt(ch, CURLOPT_POSTFIELDS, [
    'file' => new CURLFile(realpath('image.png')), 
]);

PHP 5.5另外引入了CURL_SAFE_UPLOAD选项，可以强制PHP的cURL模块拒绝旧的@语法，仅接受CURLFile式的文件。5.5的默认值为false，5.6的默认值为true。

但是坑的一点在于：@语法在5.5就已经被打了deprecated，在5.6中就直接被删除了（会产生 ErorException: The usage of the @filename API for file uploading is deprecated. Please use the CURLFile class instead）。

对于PHP 5.6+而言，手动设置CURL_SAFE_UPLOAD为false是毫无意义的。根本不是字面意义理解的“设置成false，就能开启旧的unsafe的方式”——旧的方式已经作为废弃语法彻底不存在了。PHP 5.6+ == CURLFile only，不要有任何的幻想。

我的部署环境是5.4(仅@语法)，但开发环境是5.6(仅CURLFile)。都没有压在5.5这个两者都支持过渡版本上，结果就是必须写出带有环境判断的两套代码。

现在问题来了……（挖掘机滚远点！）

环境判断：小心魔法数字！

我见过这种环境判断的代码：

if (version_compare(phpversion(), '5.4.0') >= 0)

我对这种代码的评价只有一个字：屎。

这个判断掉入了典型的魔法数字陷阱。版本号莫名其妙的出现在代码之中，不查半天PHP手册和更新历史，很难明白作者被卡在了哪个功能的变更上。

代码应该回归本源。我们的实际需求其实是：有CURLFile就优先采用，没有再退化到传统@语法。那么代码就来了：

if (class_exists('\CURLFile')) {
    $field = array('fieldname' => new \CURLFile(realpath($filepath)));
} else {
    $field = array('fieldname' => '@' . realpath($filepath));
}

建议明确指定的退化选项

从可靠的角度，推荐指定CURL_SAFE_UPLOAD的值，明确告知php是容忍还是禁止旧的@语法。注意在低版本PHP中CURLOPT_SAFE_UPLOAD常量本身可能不存在，需要判断：

if (class_exists('\CURLFile')) {
    curl_setopt($ch, CURLOPT_SAFE_UPLOAD, true);
} else {
    if (defined('CURLOPT_SAFE_UPLOAD')) {
        curl_setopt($ch, CURLOPT_SAFE_UPLOAD, false);
    }
}