PHP 上传文件临时路径与持久化移动的安全流程

PHP 上传文件的安全流程可以压缩成一句话：先检查 $_FILES 的错误码和临时文件，再校验大小与真实 MIME，最后使用服务端生成的文件名调用 move_uploaded_file()，把文件放入不对外执行的持久化目录。客户端传来的 name 只用于展示，不能直接拼接到目标路径。

官方文档：https://www.php.net/manual/en/features.file-upload.php

临时路径是 PHP 在请求期间管理的上传载体，持久化文件则应该由应用重新命名并存入隔离目录。验证通过不等于文件可以公开访问，目录位置和 Web 服务器执行策略同样重要。

先记住三个判断：① error 不是空字符串，必须比较 UPLOAD_ERR_OK；② 扩展名只能做辅助提示，类型应从文件内容读取；③ move_uploaded_file() 成功后临时文件不再是应用的持久化地址。

先分清临时文件、错误码和最终文件

表单使用 multipart/form-data 提交后，PHP 会在临时目录生成上传文件，并把它的路径放入 $_FILES['document']['tmp_name']。name 是客户端文件名，size 是上传大小，type 是客户端声明的类型，不能单独作为安全依据。上传超限、没有临时目录、部分上传等情况，要从 error 的 UPLOAD_ERR_* 常量判断。

这也解释了为什么保存逻辑不能一上来写 move_uploaded_file()：如果临时目录不可写，或者请求超过 post_max_size，$_FILES 可能不完整，应用应该先给出可定位的失败原因。

按顺序校验上传状态、大小与真实类型

实际项目可以把校验顺序固定下来：字段存在 → 错误码为零 → 文件大小在业务上限内 → 临时文件确实存在 → 使用 finfo_file() 读取内容类型 → 再检查允许的 MIME 白名单。下面的示例只接受 PDF，并将每个失败点转换成应用可记录的异常。

 $maxBytes) {
    throw new RuntimeException('文件大小不在允许范围内');
}

// finfo 读取文件内容，不信任浏览器传来的 type 或原始扩展名。
$finfo = new finfo(FILEINFO_MIME_TYPE);
$mime = $finfo->file($upload['tmp_name']);
$allowed = ['application/pdf' => 'pdf'];
if (!isset($allowed[$mime])) {
    throw new RuntimeException('文件类型不在白名单内');
}
// 这里只保存后缀映射结果，原始文件名不参与路径拼接。
$extension = $allowed[$mime];
?>

这里的 MIME 判断仍只是输入校验的一部分：如果业务会解析 PDF，还应在隔离进程或专门服务中处理内容，并限制解析资源。不要把“通过 MIME 白名单”写成“文件绝对安全”。

生成服务端文件名并准备非公开目录

持久化路径最好由租户、业务对象或日期分层，但每一级都应来自服务端已确认的标识。文件名使用随机字节或数据库 ID 加随机后缀，避免客户端提交 ../../、覆盖已有文件，或因为原名相同而让旧文件被替换。上传目录还应禁止脚本执行；若文件必须下载，可通过受控接口读取，而不是把目录直接放到公开静态资源根目录。

目录必须预先创建并由运行 PHP 的用户写入。目录权限问题发生在移动阶段，通常表现为 move_uploaded_file() 返回 false，不能靠重复调用解决。

用 move_uploaded_file 完成持久化移动

通过校验后再计算目标路径，并检查移动结果。该函数只接受 PHP HTTP 上传机制产生的文件；目标文件已存在时可能被覆盖，所以随机文件名和“不覆盖”的业务策略要同时落实。

如果后续要读取临时文件内容而不是移动它，才有必要额外调用 is_uploaded_file()。单纯移动场景由 move_uploaded_file() 自己检查来源；不要用普通 rename() 替代它来绕过上传边界。

检查配置边界与回归清单

上传失败时按下面的关系排查，比盲目调大 PHP 内存更有效：

上线前至少回归空文件、超出业务上限、超过 PHP 配置、伪造扩展名、重复上传、目标目录不可写和并发同名这几类场景。最终记录应包含错误码、MIME、大小、生成的存储名和失败阶段，但不要把临时绝对路径、用户原始路径或文件内容写进公开日志。

常见问题

为什么上传成功却找不到临时文件？临时文件只服务当前请求，过早结束请求、清理临时目录或把它当成长期 URL 都会造成误判。要在校验完成后立即移动到持久化目录。

只校验扩展名够不够？不够。扩展名可作为用户体验提示，但安全判断至少要结合错误码、大小、文件内容类型、存储目录和下载权限。