PHP 文件上传总失败怎么办：从 $_FILES 错误码到 MIME 白名单安全落盘

文件上传接口看起来很简单：前端选一个文件，后端从 $_FILES 里取出来保存。但真实项目里，问题往往出在细节上：有的用户提示上传失败，有的文件明明是图片却被拒绝，还有的接口只看后缀，留下了安全风险。

这篇文章按一次排查过程来走。我们先看现场，再一步步验证：$_FILES 里到底有什么、错误码说明了什么、为什么不能只看后缀、最后怎么把文件安全保存下来。

摘要

PHP 文件上传的稳定流程是：先检查请求方法和 $_FILES，再判断上传错误码，然后做大小限制、真实 MIME 检查、白名单比对、随机文件名生成，最后移动到指定目录并返回可控结果。重点不是把文件存下来，而是把每一步失败原因都看清楚。

适合人群

• 正在写 PHP 表单上传、头像上传、附件上传接口的开发者。
• 遇到过 $_FILES 为空、上传错误码不清楚、类型校验不稳定的问题。
• 想把“能上传”升级为“可解释、可限制、可防护”的后端同学。

问题现场：上传接口为什么偶发失败

假设我们收到一个反馈：同一个上传接口，有些文件可以上传，有些文件返回失败；日志里只有一句“上传失败”，没有说明到底失败在哪一步。

遇到这种情况，先不要急着改保存路径，也不要直接放宽限制。我们需要把上传链路拆开：浏览器提交文件，PHP 接收 $_FILES，检查错误码，验证文件类型，再保存到指定目录。

这张图对应的排查顺序很重要：先证明文件有没有到 PHP，再证明 PHP 认为它有没有上传成功，最后才看业务侧的大小和类型限制。

第一步：先看 $_FILES 的真实内容

我们先写一段最小化观察代码，不做保存，只看 PHP 接收到的数据结构。

 $file['name'] ?? '',
    'type' => $file['type'] ?? '',
    'tmp_name' => $file['tmp_name'] ?? '',
    'error' => $file['error'] ?? null,
    'size' => $file['size'] ?? 0,
]);

这里先观察五个字段：

• name：浏览器提交的原始文件名，不能直接信任。
• type：客户端提供的类型，仅可作为参考。
• tmp_name：PHP 临时文件路径，后续保存要基于它。
• error：上传错误码，这是第一优先级判断。
• size：文件大小，业务侧还要再限制一次。

如果这一步里 avatar 不存在，通常是前端字段名和后端字段名不一致，或者表单没有使用 multipart/form-data。

第二步：用错误码排除环境和表单问题

接着看 error。很多上传失败不是业务代码的问题，而是 PHP 在接收阶段已经失败了。常见错误码可以这样处理：

 'ok',
    UPLOAD_ERR_INI_SIZE => 'file too large by php.ini',
    UPLOAD_ERR_FORM_SIZE => 'file too large by form rule',
    UPLOAD_ERR_PARTIAL => 'partial upload',
    UPLOAD_ERR_NO_FILE => 'no file uploaded',
    UPLOAD_ERR_NO_TMP_DIR => 'missing temp directory',
    UPLOAD_ERR_CANT_WRITE => 'cannot write temp file',
];

if ($error !== UPLOAD_ERR_OK) {
    http_response_code(400);
    echo $messages[$error] ?? 'unknown upload error';
    return;
}

这一步可以排除不少误判。例如 UPLOAD_ERR_INI_SIZE 说明文件超过了 upload_max_filesize；如果请求整体太大，还要同步检查 post_max_size。这类问题不是改保存代码能解决的。

第三步：定位原因，不能只看后缀

现在假设错误码是 UPLOAD_ERR_OK，文件确实到了 PHP。下一步很多人会取文件后缀，然后判断是不是允许类型。问题是，后缀来自原始文件名，攻击者可以伪装。

这一步的结论是：后缀可以用于生成最终文件名，但不能作为唯一安全依据。真正的类型判断要基于服务端读取到的 MIME。

修复方案：MIME 白名单加安全文件名

下面是一段更完整的处理代码。它做了四件事：确认临时文件可信、限制大小、用 finfo 判断真实 MIME、生成随机文件名后保存。

 false, 'message' => 'upload failed'];
    }

    if (!is_uploaded_file($file['tmp_name'])) {
        return ['ok' => false, 'message' => 'invalid temp file'];
    }

    $maxBytes = 2 * 1024 * 1024;
    if (($file['size'] ?? 0) > $maxBytes) {
        return ['ok' => false, 'message' => 'file too large'];
    }

    $finfo = new finfo(FILEINFO_MIME_TYPE);
    $mime = $finfo->file($file['tmp_name']);

    $allowed = [
        'image/png' => 'png',
        'image/webp' => 'webp',
        'application/pdf' => 'pdf',
    ];

    if (!isset($allowed[$mime])) {
        return ['ok' => false, 'message' => 'file type not allowed'];
    }

    $safeName = date('YmdHis') . '-' . bin2hex(random_bytes(8)) . '.' . $allowed[$mime];
    $targetDir = __DIR__ . '/uploads';
    $targetPath = $targetDir . '/' . $safeName;

    if (!is_dir($targetDir)) {
        mkdir($targetDir, 0755, true);
    }

    if (!move_uploaded_file($file['tmp_name'], $targetPath)) {
        return ['ok' => false, 'message' => 'save failed'];
    }

    return [
        'ok' => true,
        'path' => '/uploads/' . $safeName,
        'mime' => $mime,
    ];
}

这里有几个细节值得单独说明。

• is_uploaded_file 用来确认临时路径确实来自 HTTP 上传。
• finfo 判断的是文件内容对应的 MIME，不依赖用户提交的文件名。
• 最终文件名由服务端生成，避免覆盖、路径穿越和奇怪字符。
• 保存目录最好与业务访问路径分开管理，不要直接相信用户提交的路径信息。

最后验证：成功、失败和边界都要可解释

修复后不要只测一张正常图片。建议至少验证下面几类情况：

如果这些边界都能给出明确返回，上传接口才算从“能跑”进入“可维护”的状态。

常见误区

误区一：直接使用原始文件名

原始文件名来自用户输入，可能包含重复名称、特殊字符或路径片段。保存文件时应由服务端生成新名称。

误区二：只看 $_FILES['type']

这个字段来自客户端，不适合作为最终安全判断。服务端应该用 finfo 读取真实 MIME。

误区三：只处理成功路径

上传失败时如果只返回“失败”，排查成本会很高。错误码、大小限制、类型限制、保存失败都应该有不同返回。

总结

PHP 文件上传的核心不是一句 move_uploaded_file，而是一条完整检查链路：字段存在、错误码正常、临时文件可信、大小合理、MIME 命中白名单、文件名安全、保存结果可验证。

下次遇到上传失败时，可以按本文顺序排查。先看 $_FILES，再看错误码，接着看 MIME 和白名单，最后检查保存目录和返回结果。这样问题会从模糊的“上传失败”，变成可以定位和修复的具体节点。