如何通过ThinkPHP结合分布式存储和分片上传优化文件上传效率？

本文共计1185个文字，预计阅读时间需要5分钟。

由于默认使用的PHP配置中，全局变量+$FILES+读取完整文件到内存或临时目录，大文件（>50MB）或多用户同时上传时，可能会触发PHP的+upload_max_filesize+、+post_max_size+限制，还可能耗尽+memory_limit+。ThinkPHP的+File::moveTo()+是同步阻塞操作，没有分片、没有走流式处理，一次请求就是一个完整的生命周期。

常见错误现象：413 Request Entity Too Large、502 Bad Gateway（Nginx 超时）、PHP Warning: POST Content-Length exceeds...。

• 别直接改 php.ini 把 upload_max_filesize 拉到 2G——治标不治本，反而放大单点压力
• 不要在控制器里写 $file->validate(['size'=>20971520])->move(...) 处理 1GB 视频——PHP 进程会挂住十几秒
• 注意 ThinkPHP 版本：v6.0+ 支持 think\File 的 getStream()，v5.1 需手动封装流读取

怎么用 WebUploader 或 Uppy 做前端分片上传

核心是把一个大文件切成固定大小的块（如 5MB/片），每片独立发请求，后端只收片、存片、校验 MD5，最后合并。ThinkPHP 不内置分片逻辑，得自己接。

使用场景：用户上传 >100MB 视频、CAD 文件、数据库备份包；需要断点续传或进度反馈。

立即学习“PHP免费学习笔记（深入）”；

• 前端必须生成唯一 file_id（建议用文件名+大小+最后修改时间的 MD5），所有分片共用这个 ID
• 后端接口路径别用 /upload，改用 /api/upload/chunk 和 /api/upload/merge，避免和原生上传路由冲突
• 每个分片请求带三个关键参数：chunkIndex（从 0 开始）、totalChunks、file_id，后端靠它们定位存储位置
• 分片存储路径建议按 file_id 哈希散列，比如 runtime/chunks/{substr($file_id,0,2)}/{$file_id}/，防止单目录文件过多

如何对接 MinIO 或 Aliyun OSS 实现分布式存储

本地磁盘扛不住并发写入，也难做横向扩展。ThinkPHP 本身不绑定存储驱动，但 v6.0+ 的 think\Filesystem 支持自定义适配器，v5.1 得用 league/flysystem 手动桥接。

性能影响：OSS 直传（前端签名后直传）比“后端中转”快 3–5 倍，且不占 PHP 内存；但需要后端生成临时 STS Token 或 Policy 签名。

• 别让 ThinkPHP 的 $file->move() 直接往 OSS 写——它只支持本地路径，强行传 https://xxx.oss... 会报 Invalid path
• v6.0 推荐用 think-filesystem-oss 扩展，配置里填 endpoint、access_key、secret_key、bucket 即可，上传调用 Filesystem::put($path, $stream)
• 分片合并阶段，别在 PHP 里把所有 chunk 下载回来再拼——用 OSS 的 CompleteMultipartUpload API 或 MinIO 的 composeObject，服务端完成
• 注意 OSS 的 partSize 最小 100KB，MinIO 建议设为 5MB，和前端分片大小对齐，否则合并失败

merge 合并逻辑里最容易漏掉的三件事

分片上传最脆弱的环节不是上传，是合并。很多线上问题都出在这一步：文件变花、MD5 对不上、部分分片丢失。

• 合并前必须校验所有分片的 ETag（OSS）或 md5（MinIO/本地），缺一片就中断，不能跳过或补零
• 别用 fopen('wb') 然后循环 fwrite ——大文件会吃光内存，改用 stream_copy_to_stream() 或分批 file_put_contents($file, $chunk, FILE_APPEND | LOCK_EX)
• 合并成功后，立刻删掉原始分片目录，但要用原子操作：先 rename() 分片目录为 xxx_merged_lock，再删，避免并发合并时误删
• 如果用 OSS，CompleteMultipartUpload 必须按 chunkIndex 升序提交 PartNumber，错一位整个合并就失败，错误信息是 InvalidPart

分片上传不是加个前端库就完事，真正的坑都在合并路径的幂等性、分片清理的竞态、以及云存储 API 的细节约束上。这些地方少一个 LOCK_EX 或错一个 PartNumber，用户就看到“上传成功但文件打不开”。