php实现文件分片上传的核心做法是前端将大文件切割为多个块并附带元数据依次post到服务器,后端通过接收到的`chunk_index`、`total_chunks`和`file_id`等参数将每个块写入临时目录,待所有块接收完毕后合并为一个完整的临时文件,最后将其移动至目标存储路径。具体操作中,需确保每次请求都携带唯一的`file_id`以关联同一文件的各个分片,并在处理完最后一个分片时执行合并逻辑,从而保证数据的完整性和上传的可靠性。

如何设计API接口以接收单个分片数据
接收分片的关键在于验证请求中的元数据是否完整,并将二进制流安全地写入磁盘。接口通常接受`file_id`、`chunk_index`、`total_chunks`以及分片文件本身,后端代码需检查这些字段是否存在,防止恶意或错误的请求导致数据混乱。对于每个分片,我们创建一个以`file_id`和`chunk_index`命名的临时文件,将`$_FILES`中的数据直接复制进去,这样即使某个分片上传失败,也不会影响其他分片的存储,便于后续重试机制的处理。

<?php
// upload_chunk.php
header('Content-Type: application/json');
if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
echo json_encode(['error' => 'Method not allowed']);
exit;
}
$fileId = $_POST['file_id'] ?? '';
$chunkIndex = intval($_POST['chunk_index'] ?? -1);
$totalChunks = intval($_POST['total_chunks'] ?? 0);
if (empty($fileId) || $chunkIndex < 0 || $totalChunks <= 0) {
echo json_encode(['error' => 'Missing metadata']);
exit;
}
if (!isset($_FILES['chunk'])) {
echo json_encode(['error' => 'No file chunk received']);
exit;
}
$uploadDir = sys_get_temp_dir() . '/uploads/' . $fileId;
if (!is_dir($uploadDir)) {
mkdir($uploadDir, 0777, true);
}
$chunkFile = $uploadDir . '/chunk_' . $chunkIndex;
if (move_uploaded_file($_FILES['chunk']['tmp_name'], $chunkFile)) {
echo json_encode(['status' => 'ok', 'chunk' => $chunkIndex]);
} else {
echo json_encode(['error' => 'Failed to save chunk']);
}
?>上述代码展示了基本的分片接收逻辑。它首先校验了必要的POST参数,然后构建了基于`file_id`的独立目录结构。使用`move_uploaded_file`函数将PHP生成的临时文件移动到指定位置,这是最安全的做法,因为它能自动处理权限检查和临时文件清理。如果保存成功,返回状态码供前端确认;如果失败,前端可根据错误信息进行重试。这种设计确保了每个分片都是独立的实体,降低了单点故障对整体上传任务的影响。
立即学习“PHP免费学习笔记(深入)”;
使用官方Model Context Protocol PHP SDK将PHP应用程序功能暴露为MCP工具、资源和提示,用于代理工作流。
如何判断所有分片已就绪并合并文件
当所有分片上传完成后,前端会发起一个合并请求,或者在后端检测到最后一个分片到达时触发合并。我们需要一个专门的接口来检查进度或直接执行合并。合并过程涉及读取该`file_id`目录下所有的`chunk_*`文件,按照`chunk_index`的顺序依次读取内容并追加到一个新的完整文件中。在合并开始前,应再次验证分片数量是否与`total_chunks`一致,防止因网络波动导致的分片丢失。合并完成后,将生成的完整文件移动到最终的存储目录,并清理临时目录下的所有分片文件,释放磁盘空间。

<?php
// merge_file.php
header('Content-Type: application/json');
$fileId = $_POST['file_id'] ?? '';
$totalChunks = intval($_POST['total_chunks'] ?? 0);
if (empty($fileId) || $totalChunks <= 0) {
echo json_encode(['error' => 'Invalid parameters']);
exit;
}
$uploadDir = sys_get_temp_dir() . '/uploads/' . $fileId;
if (!is_dir($uploadDir)) {
echo json_encode(['error' => 'Upload directory not found']);
exit;
}
// 检查所有分片是否存在
for ($i = 0; $i < $totalChunks; $i++) {
if (!file_exists($uploadDir . '/chunk_' . $i)) {
echo json_encode(['error' => 'Missing chunk ' . $i]);
exit;
}
}
$finalFile = sys_get_temp_dir() . '/uploads/' . $fileId . '.final';
$fp = fopen($finalFile, 'wb');
for ($i = 0; $i < $totalChunks; $i++) {
$chunkPath = $uploadDir . '/chunk_' . $i;
$chunkData = file_get_contents($chunkPath);
fwrite($fp, $chunkData);
unlink($chunkPath); // 合并后立即删除分片
}
fclose($fp);
// 移动最终文件到持久化存储
$destination = '/var/www/uploads/' . basename($fileId);
mkdir(dirname($destination), 0777, true);
if (rename($finalFile, $destination)) {
rmdir($uploadDir); // 清理空目录
echo json_encode(['status' => 'merged', 'path' => $destination]);
} else {
echo json_encode(['error' => 'Failed to move final file']);
}
?>这段代码实现了完整的合并逻辑。它首先遍历预期的分片索引,确保每个分片文件都存在,这是保证文件完整性的关键步骤。接着,它打开一个写模式的文件指针,按顺序读取每个分片的内容并写入最终文件。每读取一个分片就立即删除,有助于控制磁盘占用。最后,使用`rename`原子操作将临时合并文件移动到生产环境目录,这不仅提高了效率,还避免了部分写入导致的文件损坏风险。整个过程严格依赖`file_id`进行隔离,确保多用户并发上传时不会发生冲突。
如果分片上传过程中断如何处理残留数据
在实际运行中,网络中断或客户端崩溃可能导致部分分片留在临时目录中,形成“孤儿”数据。为了解决这个问题,需要引入定期清理机制或手动清理接口。我们可以编写一个简单的脚本,扫描临时上传目录,查找那些超过一定时间(如24小时)未被合并的文件夹,并将其整个删除。此外,在合并接口中,如果发现某些分片缺失且无法补传,也应提供重置功能,允许前端重新发起上传,此时后端应清空该`file_id`对应的旧有分片数据,避免新旧数据混合。这种清理策略保证了服务器磁盘空间的可持续利用,防止因大量未完成上传任务导致的资源耗尽。


















