php如何实现文件上传功能：表单、校验与安全落盘完整流程

php如何实现文件上传功能，一条链路从浏览器表单延伸到服务器磁盘：multipart 请求被拆成若干分段、临时文件先落地、脚本校验后再搬到目标目录。链路上任何一处放松，都可能变成任意文件写入或目录穿越。按表单、数组结构、校验、落盘、服务端边界逐段拆开，每段给出可执行的配置与代码。

表单端：enctype 与字段约定

php如何实现文件上传功能，先要把表单的三个属性写对：method 为 post，enctype 为 multipart/form-data，控件是 input type="file"。漏掉 enctype，浏览器会按 urlencoded 提交，$_FILES 直接是空数组。

字段的 name 决定 $_FILES 的顶层键名。单文件写 name="avatar"，取到的就是 $_FILES['avatar']。要一次传多张，用 name="shots[]"，PHP 会把它收成嵌套数组，取值方式和单文件不同。

php如何实现文件上传功能时，多文件字段的五个键会各自摊成数组，name、size、error 都按下标对齐。取值要按下标逐个拼回一个文件，不能直接把它当成单个文件的结构读。

表单里再放一个隐藏的 token 字段做来源校验，它随文件一起提交。token 在渲染表单时用 bin2hex(random_bytes(16)) 生成并存进 session，服务端先比对再处理文件，匿名接口才不至于被直接刷。

$_FILES 结构与错误码

表单写对之后，php如何实现文件上传功能的重心转到 $_FILES 数组。每个字段固定五个键：name 是客户端文件名，type 是客户端声明的 MIME，tmp_name 是服务端临时路径，error 是状态码，size 是字节数。

name 与 type 由客户端提交，不可信；tmp_name、size、error 由 PHP 在收包时填充，可以参与判断，但 size 仍要与业务上限做二次比对。判断 error 要用常量名：0 成功，1 超过 upload_max_filesize，3 数据不全，4 没选文件，6 临时目录缺失，7 写盘失败，8 被扩展拦下。

临时文件在请求结束时由 PHP 自动删除，所以必须在本次请求内搬走。move_uploaded_file 会顺带确认来源确实是上传文件，比 rename 多一层保护。

临时目录一般落在服务器本地磁盘，由 upload_tmp_dir 指定，未设置时用系统默认位置。所在分区要有余量，空间不足时 error 停在 7，日志里看到的是写入失败而不是权限提示。

类型与大小校验

大小要卡两道：前端 max_file_size 只是提示，服务端拿 $_FILES 里的 size 和业务上限比较才算数。上限一旦超过 post_max_size，整个请求体会被丢弃，$_FILES 变空，现象和漏写 enctype 一样。

type 字段是这套流程里最不可信的一环，它由浏览器按扩展名猜出来。要用 finfo_file 读临时文件的真实 MIME，图片再叠一层 getimagesize 确认能解析，白名单只放业务需要的几种。校验做到这一步，php如何实现文件上传功能才算守住入口。

扩展名由白名单映射生成，不要直接截取客户端文件名的后缀。名为 shell.php.jpg 的文件在部分旧配置下仍会被当作脚本执行，给上传目录关掉脚本解析是另一道保险。

把校验看成几道串联的闸门更好理解：请求体先过服务端限制，再进临时目录，然后逐项比对大小、MIME、扩展名，全部通过才允许搬移。任何一道返回失败就结束请求，并记下原因。

落盘：目录、命名与权限

落盘这一步最容易被简化成一句 move。目标目录放在 web 根之外，由脚本按权限转发下载，上传目录就不会被直接浏览。

确实要放进 web 根内时，至少给该目录关掉脚本解析。文件名由服务端生成，时间戳加随机串，后缀取自白名单映射；原始文件名只入库供展示，不参与路径拼接。命名与权限都由服务端决定，这一层才决定php如何实现文件上传功能的安全下限。

客户端文件名可能带 ../ 或者超长中文，落盘前先跑一遍 basename 与长度截断，只留展示用的副本，路径部分永远由服务端拼。

下面这段逻辑把前面的判断串起来：先看 error，再验来源与大小，最后按 MIME 反查后缀生成新名并搬移。返回值只区分结果，不把内部路径带出去。

<?php
session_start();
$expect = $_SESSION['upload_token'] ?? '';
if ($expect === '' || !hash_equals($expect, $_POST['token'] ?? '')) {
    exit('csrf');
}
$field = 'avatar';
$dir   = '/srv/app/storage/uploads/';
$max   = 5 * 1024 * 1024;
$allow = [
    'jpg' => 'image/jpeg',
    'png' => 'image/png',
    'pdf' => 'application/pdf',
];

if (!isset($_FILES[$field]) || $_FILES[$field]['error'] !== UPLOAD_ERR_OK) {
    exit('upload failed');
}
$file = $_FILES[$field];
if ($file['size'] > $max || !is_uploaded_file($file['tmp_name'])) {
    exit('size or source rejected');
}
$finfo = new finfo(FILEINFO_MIME_TYPE);
$mime  = $finfo->file($file['tmp_name']);
$ext   = array_search($mime, $allow, true);
if ($ext === false) {
    exit('mime rejected');
}
$name = bin2hex(random_bytes(8)) . '.' . $ext;
if (!move_uploaded_file($file['tmp_name'], $dir . $name)) {
    exit('move failed');
}
echo 'stored as ' . $name;

array_search 从 MIME 反查后缀，比截取原文件名更稳。random_bytes 自 PHP 7 起可用，更早的版本可以换成 openssl_random_pseudo_bytes，并检查它的强度返回值。

nginx 与 php.ini 的边界

不少请求其实倒在配置文件这一关：upload_max_filesize 管单个文件，post_max_size 管整个请求体，后者要覆盖前者加上其他字段的体积，改完重启 php-fpm。

nginx 还有 client_max_body_size，默认 1m，请求体超过它直接返回 413，PHP 根本没被调用，日志里只有一行访问记录。反向代理场景下，每一层都要放开同一个量级。

三处上限对齐到同一数量级，改动收在一段配置里更好维护。

server {
    listen 80;
    server_name example.com;
    client_max_body_size 8m;
    client_body_timeout 60s;

    location = /upload {
        include fastcgi_params;
        fastcgi_pass unix:/run/php/php-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $document_root/upload.php;
    }
}

location = /upload 是精确匹配，配合显式写死的 SCRIPT_FILENAME，请求才会落到 upload.php；沿用 $fastcgi_script_name 时它等于 /upload，php-fpm 会去找一个不存在的文件，报 Primary script unknown。socket 路径随发行版不同，Debian 系一般是 php8.x-fpm.sock，以官方文档为准。

client_max_body_size 的单位是 m 或 k，可写在 http、server、location 任一层，内层覆盖外层。传大文件还要看 fastcgi_read_timeout，超时会让连接断开，而文件可能已经部分落盘。

机器走反向代理时，请求先到 nginx 再到 fpm，两个进程未必在同一台机器。遇到 413 或 502，先确认命中的是哪一层的配置，再改参数。

排查顺序：从 413 到空数组

php如何实现文件上传功能，排查时按层往下走最快。先看响应码：413 是 nginx 拦的，500 多为脚本报错，302 常见于框架中间件重定向，一步就能把范围缩小到某层。

进了 PHP 再按 error 分叉：值正常但文件没出现，多半是 move 失败，查目录权限与 SELinux 上下文；值为 1 或 2 是上限问题；为 6 是临时目录不可写；空数组则回到表单和服务端限制。

install -d -m 0750 -o www-data -g www-data /srv/app/storage/uploads
curl -F "avatar=@./test.png" -F "token=替换为表单里的值" http://example.com/upload
ls -l /srv/app/storage/uploads

三行依次用于建目录、发一次带 token 的真实请求、确认落盘结果。目录权限给 750、属主给 web 进程用户就够，777 只会让问题更难查。

把这套顺序写成清单，php如何实现文件上传功能就不再是黑盒，遇到报错按层核对，比在代码里到处打日志省事。