PHP-FPM 上传临时文件越积越多：upload_tmp_dir、清理时机与失败回收

凌晨收到磁盘告警，通常不会第一时间想到根因出在上传临时文件上。如果你的PHP-FPM服务器上的 /tmp 或者自定义 upload_tmp_dir 占用空间持续上涨，同时最近上传接口刚出现过超时、进程重启或是业务报错，临时文件没落到最终存储路径也没被及时回收，基本就是头号排查目标。处理这类问题的核心不是登服务器删掉存量文件就完事，而是把临时文件从创建、校验、移动到失败清理的整条链路逐段核对清楚。

先确认增长来源：是临时目录满了，还是最终业务目录在变大

我更推荐先摸清楚文件增长的位置和时间分布，再动手输清理命令。下面给出的操作只会读取目录信息，不会改动或删除任何文件：

php --ini | grep -E 'Loaded Configuration|Scan for additional'
php -r 'echo ini_get("upload_tmp_dir"), PHP_EOL;'
find /tmp -maxdepth 1 -type f -mmin +30 -printf '%TY-%Tm-%Td %TH:%TM %s %p\n' | sort -k3 -nr | head -20
df -h /tmp /var/www/app/storage/uploads

如果上传临时目录里的文件是批量生成、生命周期短、大小和请求体特征匹配的状态，而业务最终存储目录的体积没有同步上涨，问题大概率出在数据接收完成后没走完交接流程。要是新生成的文件都集中在最近几分钟，先别按统一时间阈值批量清理，很可能还有耗时较长的慢上传请求正在运行。

PHP上传文件实际经过哪些状态

PHP收到上传请求后，会先把请求体里的文件数据写入临时位置，再把对应的元数据放到 $_FILES 里。业务代码得把这个临时文件当成还没完成交接的中转资源，而不是已经属于业务最终目录的正式文件。下面这张图对应的就是从接收、校验到移动或者失败回收的完整最小链路。

优先检查error属性和is_uploaded_file判断

不要只判断 $_FILES['attachment']['tmp_name'] 文件是否存在。上传大小超限、请求中途断开、临时目录不可写这类场景下，error 才是更早的分流判断信号：

$file = $_FILES['attachment'] ?? null;
if (!is_array($file) || ($file['error'] ?? UPLOAD_ERR_NO_FILE) !== UPLOAD_ERR_OK) {
    http_response_code(400);
    throw new RuntimeException('upload rejected');
}

$tmp = $file['tmp_name'];
if (!is_uploaded_file($tmp)) {
    http_response_code(400);
    throw new RuntimeException('temporary upload is invalid');
}

这时候先别急着改 upload_max_filesize 配置。如果错误码是 UPLOAD_ERR_PARTIAL，优先排查客户端断连、反向代理超时和PHP-FPM单请求最大时长限制；如果是 UPLOAD_ERR_CANT_WRITE，再去核对临时目录权限和磁盘inode占用情况。

落地处理：把成功交接和失败回收写在同一条逻辑路径里

最终存储的文件名不要直接沿用用户上传的原始名称。先生成业务侧唯一ID，再把文件移动到按日期分层的业务目录里；所有校验失败的分支，都尽量在当前请求结束前把临时文件清理掉。

$targetDir = __DIR__ . '/storage/uploads/' . date('Y/m/d');
if (!is_dir($targetDir) && !mkdir($targetDir, 0750, true)) {
    throw new RuntimeException('target directory unavailable');
}

$extension = strtolower(pathinfo($file['name'], PATHINFO_EXTENSION));
$allowed = ['jpg', 'jpeg', 'png', 'pdf'];
if (!in_array($extension, $allowed, true)) {
    throw new RuntimeException('file type rejected');
}

$target = $targetDir . '/' . bin2hex(random_bytes(16)) . '.' . $extension;
if (!move_uploaded_file($tmp, $target)) {
    throw new RuntimeException('temporary file handoff failed');
}

// 成功移动后，$tmp 不再是待回收对象
unset($tmp);

生产环境代码里，还要提前定好数据库记录和文件交接的先后顺序：如果先写数据库再移动文件，移动失败时必须给这条记录加“待补偿”状态；如果先移动文件再写数据库，数据库写入失败时就得把刚生成的目标文件丢进补偿队列。两种顺序都能正常跑通，只有逻辑含糊不清才会产生没人认领的孤儿文件。

给所有异常分支加窄范围的临时文件清理动作

$tmp = null;
try {
    $file = $_FILES['attachment'] ?? null;
    // 省略字段、大小和内容类型校验
    $tmp = $file['tmp_name'];
    if (!is_uploaded_file($tmp)) {
        throw new RuntimeException('invalid upload');
    }
    // 生成目标路径并完成移动
    $ok = move_uploaded_file($tmp, $target);
    if (!$ok) {
        throw new RuntimeException('handoff failed');
    }
    $tmp = null;
} finally {
    if (is_string($tmp) && is_file($tmp)) {
        unlink($tmp);
    }
}

finally 不是绝对的保险机制。PHP-FPM被强制终止、宿主机意外断电这类场景下，当前请求根本没有机会运行后续的清理代码，所以还是需要一个只处理“远超正常生命周期的老文件”的兜底定时任务。

紧急回滚处理：先暂停入口，再清理确认过期的文件

收到磁盘告警时，先把上传入口切到维护状态或者临时限制大文件传输，不要一边高并发写入一边清理同一个目录。确认没有长时间运行的慢上传请求后，只处理超过预设保留窗口、且不在活跃进程占用范围内的普通文件：

# 先观察，不删除
find /srv/php-upload-tmp -maxdepth 1 -type f -mmin +60 -printf '%T@ %s %p\n' | sort -n | tail -20

# 维护窗口内按白名单清理，保留最近 60 分钟文件
find /srv/php-upload-tmp -maxdepth 1 -type f -mmin +60 -delete

如果执行清理后磁盘空间没有明显回升，去检查inode占用、容器挂载点映射关系和PHP-FPM实际加载的配置文件。php --ini 读取到的CLI模式配置不一定等于FPM池加载的生效配置，必要时可以在临时健康检查页面输出 ini_get('upload_tmp_dir') 做确认，排查完就立刻删掉这段临时代码。

告警验证：怎么确认不是删完临时文件就临时凑合用

空间恢复后至少完整观察一个上传业务高峰时段，重点关注三个指标：临时目录总文件数、临时目录总占用字节、上传请求失败率。单次 df -h 告警变绿只能说明磁盘空间暂时释放了，不能证明异常流程的失败回收逻辑已经闭环。

后续优化：把临时文件状态变成可观测的业务信号

日志里记录上传请求ID、错误码、临时文件目录、文件字节数和交接耗时，但不要记录完整的客户端原始文件名或者文件内容。目录监控可以按文件数和总字节数分别设置阈值，比如文件数连续10分钟上涨但业务最终目录体积没有同步增加，就触发低级告警；磁盘使用率超过85%时直接触发限制大文件上传的预案。

还要把清理任务做成全配置可管控的模式：文件保留窗口、允许扫描的目标目录、单次最大删除数量都从配置中心读取，新配置首次上线时只输出待清理候选列表不实际执行删除。这样哪怕线上配置写错，也能先停下任务调整，不至于面对已经执行完的批量删除结果。

常见问题

upload_tmp_dir 和 sys_temp_dir 是同一个配置吗？

不是。upload_tmp_dir 专门控制文件上传产生的临时文件存放位置；sys_temp_dir 是PHP通用系统临时目录配置。两个配置都以FPM进程实际加载的生效值为准，不要只参考CLI模式下读取到的配置结果。

move_uploaded_file 执行成功后还需要手动调用 unlink 删除吗？

通常不需要。文件已经被移动到新路径，原来的临时路径下已经不存在对应文件，重复执行删除只会打满无意义的错误日志。只有异常分支场景下，才需要确认路径确实属于上传临时目录后再做清理。

可以每分钟跑个定时任务直接清空 upload_tmp_dir 目录吗？

不建议这么做。间隔过短的清理任务很容易删掉还在传输中的慢上传文件。要先设置明确的文件年龄阈值、先观察全量活跃请求状态、配置好目录白名单，预览完待清理列表再执行实际删除操作。

小结

PHP-FPM上传临时文件堆积，通常不是单独的“清理脚本出问题”，而是文件接收、校验、移动和异常回收整条链路里缺了一段可靠的交接逻辑。先定位进程实际在用的临时目录，再让成功路径和失败路径都能输出明确的状态，最后用超期文件兜底清理 + 文件数/字节数双维度告警做收口，线上处理这类问题才不会一直停留在出事就删文件的层面。