当前位置：首页 > 文章列表 > 文章 > php教程 > PHP 表单上传大文件怎么做断点续传：分片校验、临时文件与合并

PHP 表单上传大文件怎么做断点续传：分片校验、临时文件与合并

来源：17golang原创 2026-08-25 01:13:05 0浏览收藏

大文件上传最麻烦的地方不是把一个 $_FILES 写进磁盘，而是用户传到 80% 时网络断了，下一次打开页面还得从头来。更稳妥的做法是把文件拆成固定大小的分片，每片单独校验并落到任务目录，服务端只在所有分片齐全且顺序正确时合并成最终文件。

断点续传的核心不是“记住上传进度”，而是让客户端能查询已完成分片，并让服务端用文件哈希、分片编号和临时目录把一次上传任务区分开。

要点速览：

用 upload_id 隔离每一次上传任务。
分片写入临时目录并在改名后返回成功。
合并前检查分片总数，完成后核对整文件哈希。
失败任务保留状态并按规则清理临时文件。

先把上传协议定清楚

建议把一次上传抽象成三个接口：创建任务、上传分片、查询与合并。客户端第一次提交文件名、文件总大小、总分片数和整文件哈希，服务端返回不可猜测的 upload_id。后续请求只携带这个 ID、分片编号、分片总数和当前二进制内容。

分片编号从 0 开始，服务端文件名统一使用 000000.part 这样的格式，不直接相信客户端传来的原始文件名。原始文件名只作为展示字段，最终保存名应由服务端生成。

POST /upload/init
{
  "name": "backup.zip",
  "size": 524288000,
  "parts": 50,
  "sha256": "整文件哈希"
}

PHP 接收分片时先做边界校验

上传接口收到请求后，第一件事是检查任务是否存在、分片编号是否在范围内、分片大小是否超过上限。不要把用户传来的文件名直接拼进路径，也不要用“文件存在就算成功”的判断，因为上次中断可能留下半截文件。

= $total) {
    http_response_code(422);
    exit('invalid part metadata');
}

$root = __DIR__ . '/runtime/uploads/' . basename($uploadId);
if (!is_dir($root) && !mkdir($root, 0700, true)) {
    throw new RuntimeException('cannot create upload directory');
}
$target = $root . '/' . sprintf('%06d.part', $part);
$input = fopen('php://input', 'rb');
$output = fopen($target . '.tmp', 'wb');
stream_copy_to_stream($input, $output);
fclose($input);
fclose($output);
rename($target . '.tmp', $target);
echo json_encode(['ok' => true, 'part' => $part]);

示例中的临时文件和改名动作很重要：合并逻辑永远只读取已经改名完成的 .part 文件，不会碰到正在写入的临时文件。生产环境还应限制任务目录的属主和访问权限，并把上传 ID 与登录用户绑定。

查询接口要返回“已完成哪些片”

客户端重试前先调用查询接口。服务端扫描当前任务文件夹，只认符合六位数字编号的分片，并返回编号数组、总分片数和任务状态。不要只返回一个百分比，百分比无法告诉客户端缺的是哪一片。

$done = [];
foreach (glob($root . '/*.part') as $file) {
    if (preg_match('/\/(\d{6})\.part$/', $file, $m)) {
        $done[] = (int) $m[1];
    }
}
sort($done);
echo json_encode(['parts' => $done, 'status' => 'uploading']);

如果查询结果中已经有当前分片，客户端可以跳过它；如果只有临时文件，没有对应的 .part 文件，就继续上传。这样即使浏览器刷新，也不会把“正在写入”误当成成功。

合并前后分别做一次检查

合并接口不能只检查目录里有多少文件。它应该按 0 到 total - 1 逐片打开，确认每个分片存在，再使用二进制方式追加到一个新的临时目标文件。任何一片缺失都返回可重试的状态，而不是生成一个看似完整的坏文件。

$mergedTmp = $root . '/result.tmp';
$out = fopen($mergedTmp, 'wb');
for ($i = 0; $i

合并完成后再计算最终文件的 SHA-256，并与初始化时记录的值比较。哈希不一致时，删除最终文件并把任务标记为失败，保留缺片信息供客户端重新上传。不要因为 HTTP 200 就认为文件可用。

错误码要让调用方知道下一步

上传接口可以用 422 表示元数据错误，用 404 表示任务不存在，用 409 表示分片缺失或任务状态冲突，用 507 表示磁盘空间不足。响应体再补一个稳定的业务字段，例如 part_missing、checksum_mismatch 或 uploading，前端就能区分“重新传这一片”和“重新创建任务”。

重试也要有边界：同一分片可以重传，合并请求可以带幂等键，但不要在服务端无限重试文件操作。磁盘写满、权限错误和哈希不一致都需要留下日志，方便定位。