Laravel/Flysystem上传S3文件时如何正确关闭文件句柄？

你手动执行fclose仅能释放自己打开的本地文件句柄，持续累积的泄漏流来自3个位置：

• 调用put传入文件句柄时，Flysystem S3适配器底层依赖的AWS SDK会自动创建HTTP请求流、分段上传缓冲流
• Guzzle HTTP客户端默认会保留响应流引用，不会在请求结束后自动关闭
• PHP的循环引用垃圾回收默认不会在foreach循环执行过程中主动触发，无引用的流对象会一直占着文件句柄直到脚本结束
  调高ulimit -n只是推迟崩溃阈值，没有从源头释放资源，文件量足够大时依然会触发句柄耗尽错误。

优先方案：改用原生文件上传方法，去掉手动文件句柄操作 #

你手动fopen打开句柄再传给put的写法完全多余，Laravel Storage提供了专门的本地文件上传方法，底层会自动管理所有流资源的打开与关闭，从根源避免泄漏。替换循环内逻辑如下：

foreach ($localFiles as $file) {
    if (Str::startsWith($file, '.')) {
        continue;
    }

    $localLocation = $localBaseDir . $file;
    $remoteLocation = $remoteBaseDir . $file;

    // 直接传入本地文件路径，无需手动开关句柄
    $remoteDisk->putFileAs(
        dirname($remoteLocation),
        $localLocation,
        basename($remoteLocation)
    );

    $localDisk->delete($file);
    // 每轮循环主动触发垃圾回收，释放无引用的流对象
    gc_collect_cycles();
}

注意：你之前打开文件用的ab+是读写追加模式，上传仅需读权限，这个模式本身还会带来不必要的文件锁风险，完全没必要使用。

兼容方案：手动清理SDK残留资源 #

如果你的场景必须手动传入文件句柄（比如需要在上传前对流内容做实时处理），每次上传完成后手动清空SDK和HTTP客户端持有的流引用即可，在fclose($fileHandle)后追加以下代码：

// 清空S3 SDK内部缓存的命令、请求资源
$remoteDisk->getAdapter()->getClient()->flush();
// 主动触发垃圾回收
gc_collect_cycles();

如果使用该方案依然有资源泄漏，先把aws/aws-sdk-php依赖升级到最新稳定版，3.200之前的版本确实存在Guzzle响应流不主动关闭的已知bug，官方已经在后续版本修复。

大量文件场景优化：分块重置磁盘实例 #

如果需要处理的文件量超过千级，不要一次性加载全量文件列表，也不要长期复用同一个S3磁盘实例，每处理20-30个文件重置一次实例，彻底释放实例持有的所有资源：

$perChunk = 25;
collect($localFiles)->chunk($perChunk)->each(function ($fileChunk) use ($localBaseDir, $remoteBaseDir, $localDisk) {
    // 每块处理前重新初始化远程磁盘实例
    $remoteDisk = Storage::disk('some_remote_disk');
    foreach ($fileChunk as $file) {
        if (Str::startsWith($file, '.')) {
            continue;
        }
        $localLocation = $localBaseDir . $file;
        $remoteLocation = $remoteBaseDir . $file;
        $remoteDisk->putFileAs(dirname($remoteLocation), $localLocation, basename($remoteLocation));
        $localDisk->delete($file);
    }
    // 释放当前块的远程磁盘实例引用
    unset($remoteDisk);
    gc_collect_cycles();
});

• 不要把整个文件读取为字符串传入put方法，大文件会直接占满内存，稳定性比流泄漏还差
• 不需要额外引入S3 CLI客户端，上述纯PHP实现的稳定性和性能完全可以满足定时任务场景需求
• 不要依赖调高系统文件句柄上限作为解决方案，这只是延后故障发生的时间，无法根治问题

内容的提问来源于stack exchange，提问作者Pelmered