PHP 文件上传生命周期：从表单校验到存储和过期清理

PHP 文件上传看起来只是一句 move_uploaded_file，但线上真正要管的是完整生命周期：文件从浏览器表单进来，经过大小、扩展名、MIME、内容校验，再从临时目录转存到业务目录，最后还要有数据库记录、访问路径和过期清理策略。

本文按数据流转来拆一个头像上传接口，重点放在“每一段数据在哪里、谁负责校验、失败后如何处理”。

数据来源：浏览器表单到 $_FILES

上传的第一站是 HTML 表单。表单必须使用 multipart/form-data，后端才能在 $_FILES 中拿到文件信息。

  上传头像

后端拿到的不是一个最终文件，而是一组上传元信息：临时路径、原始文件名、MIME、大小和错误码。第一步要先确认字段存在。

 '缺少上传字段']);
    return;
}

$file = $_FILES['avatar'];

校验阶段：大小、类型和错误码先拦截

不要相信浏览器传来的文件名和 MIME。浏览器的 accept 只能改善用户体验，不能替代服务端校验。后端至少要检查三个点：上传错误码、文件大小、真实 MIME。

 '文件上传失败']);
    return;
}

if ($file['size']  $maxBytes) {
    http_response_code(400);
    echo json_encode(['message' => '文件大小不符合要求']);
    return;
}

$finfo = new finfo(FILEINFO_MIME_TYPE);
$mime = $finfo->file($file['tmp_name']);
$allowed = [
    'image/jpeg' => 'jpg',
    'image/png' => 'png',
];

if (!isset($allowed[$mime])) {
    http_response_code(400);
    echo json_encode(['message' => '仅支持 JPG 或 PNG']);
    return;
}

这一步的目标是把明显不合法的输入挡在业务存储之前。否则恶意文件一旦落盘，后续清理和排查都会更难。

存储模型：临时文件如何变成业务文件

PHP 上传成功后，文件先在临时目录。业务代码要把它移动到可控目录，并生成新的文件名。不要直接使用用户原始文件名，因为它可能包含特殊字符、重复名或伪造扩展名。

 '存储目录创建失败']);
    return;
}

$newName = bin2hex(random_bytes(16)) . '.' . $ext;
$targetPath = $baseDir . '/' . $newName;

if (!move_uploaded_file($file['tmp_name'], $targetPath)) {
    http_response_code(500);
    echo json_encode(['message' => '文件保存失败']);
    return;
}

$relativePath = '/uploads/avatar/' . $dateDir . '/' . $newName;

这里用日期目录减少单目录文件数量，用随机文件名避免冲突。生产环境还可以把上传目录放在独立磁盘、对象存储或静态资源域名下。

查询路径：数据库只存相对路径和元信息

数据库不建议存文件二进制内容。多数业务只需要保存相对路径、原始文件名、MIME、大小、所属用户和创建时间。

CREATE TABLE user_avatar_file (
  id BIGINT PRIMARY KEY AUTO_INCREMENT,
  user_id BIGINT NOT NULL,
  path VARCHAR(255) NOT NULL,
  mime VARCHAR(64) NOT NULL,
  size_bytes INT NOT NULL,
  created_at DATETIME NOT NULL,
  status VARCHAR(20) NOT NULL
);

prepare(
    'INSERT INTO user_avatar_file
     (user_id, path, mime, size_bytes, created_at, status)
     VALUES (:user_id, :path, :mime, :size_bytes, NOW(), :status)'
);

$stmt->runQuery([
    ':user_id' => $userId,
    ':path' => $relativePath,
    ':mime' => $mime,
    ':size_bytes' => (int) $file['size'],
    ':status' => 'active',
]);

注意上面的 runQuery 是项目里封装的安全方法示例；如果使用原生 PDO，请根据项目规范调用绑定参数的方法。不要把用户输入拼接进 SQL。

异常处理：上传失败要返回可判断原因

上传失败不能只返回“系统错误”。前端需要知道是文件太大、类型不支持，还是服务器保存失败。建议使用稳定错误码，让前端可以做分支提示。

{
  "code": "FILE_TOO_LARGE",
  "message": "文件大小不能超过2MB"
}

同时，服务端日志应记录字段名、用户 ID、MIME、大小、保存路径和失败阶段。不要把完整文件内容写入日志。

清理策略：未绑定文件和旧头像怎么删

文件上传成功并不代表生命周期结束。常见清理场景有两个：

• 用户上传后没有完成业务提交，文件处于临时或未绑定状态。
• 用户替换头像后，旧头像不再被引用。

可以用状态字段配合定时任务处理。比如未绑定文件超过 24 小时后删除，旧头像在新头像确认生效后标记为 deleted。

SELECT id, path
FROM user_avatar_file
WHERE status = 'pending'
  AND created_at 

总结一下，PHP 文件上传要按生命周期设计：来源字段可识别，校验在落盘前完成，存储目录和文件名由服务端生成，数据库只记录路径和元信息，失败返回稳定原因，最后用清理策略处理无人引用的文件。