PHP $_FILES中error返回值详解

顾星河

发布时间：2026-10-14| 6人浏览过

原创

在进行PHP文件上传开发时，$_FILES 超全局数组中的 error 字段是判断上传是否成功的核心指标。了解其具体的数值含义，能快速定位网络中断、文件大小超限或服务器配置不当等问题。

常见的错误返回值含义

当执行文件上传脚本时，$_FILES['file']['error']（假设输入字段名为 'file'）会返回一个整数代码。以下是 PHP 内置常量对应的具体含义：

UPLOAD_ERR_OK (0)：
表示文件已成功上传至服务器的临时目录，无任何错误发生。
UPLOAD_ERR_INI_SIZE (1)：
上传的文件大小超过了 php.ini 配置文件中 upload_max_filesize 指令所设定的最大值。这是最常见的服务器端限制错误。
UPLOAD_ERR_FORM_SIZE (2)：
上传的文件大小超过了 HTML 表单中隐藏的 MAX_FILE_SIZE 域指定的值。通常用于在前端页面提前拦截过大的文件。
UPLOAD_ERR_PARTIAL (3)：
文件只有部分被上传。这通常是由于网络连接不稳定或上传过程中用户关闭了浏览器导致的。
UPLOAD_ERR_NO_FILE (4)：
没有文件被上传。检查表单的 enctype 属性是否正确设置为 multipart/form-data，或者前端确实未选择任何文件。
UPLOAD_ERR_CANT_WRITE (7)：
文件写入磁盘失败。这通常是因为目标文件夹权限不足，或者磁盘空间已满。
UPLOAD_ERR_EXTENSION (8)：
由于 PHP 扩展的原因导致文件上传被中止。例如相关的文件处理扩展未被启用或存在冲突。

第1步：检查环境配置与日志

若遇到上传失败，首先应检查 php.ini 文件中的关键参数，如 file_uploads 是否为 On，以及 upload_tmp_dir 指向的临时目录是否存在且拥有正确的读写权限（通常为 755 或 777，视服务器安全策略而定）。

第2步：使用 Switch 语句进行标准化错误处理

在业务逻辑中，建议直接使用 switch-case 结构对 $error 值进行处理，以确保每种异常情况都有明确的反馈机制。

switch ($_FILES[$field]['error']) {    case UPLOAD_ERR_OK:        // 上传成功，可继续后续存储逻辑        break;    case UPLOAD_ERR_INI_SIZE:        // 超出 php.ini 限制        echo "The file is too large (server config).";        break;    case UPLOAD_ERR_FORM_SIZE:        // 超出表单 MAX_FILE_SIZE 限制        echo "The file is too large (form limit).";        break;    case UPLOAD_ERR_PARTIAL:        // 仅部分上传        echo "The file was only partially uploaded.";        break;    case UPLOAD_ERR_NO_FILE:        // 无文件上传        echo "No file was uploaded.";        break;    case UPLOAD_ERR_NO_TMP_DIR:        // 缺少临时文件夹        echo "Missing temporary folder.";        break;    case UPLOAD_ERR_CANT_WRITE:        // 写入失败        echo "Failed to write the file to disk.";        break;    case UPLOAD_ERR_EXTENSION:        // 扩展停止上传        echo "A PHP extension stopped the upload process.";        break;    default:        // 未知错误        echo "Unknown error code: " . $_FILES[$field]['error'];        break;}