PHP大文件上传失败？从Nginx到Worker的分片上传实战

大文件上传是我特别不乐意接，但又几乎每个项目都会撞上的需求。有段时间我连续帮人排查过几个PHP项目的上传故障：有的跑在Windows + IIS上，有的跑在Linux + Nginx上，还有Apache跑了一堆老系统，它们的共同点是——图片、PDF这些几MB的小东西没问题，换成几百MB的视频压缩包，要么直接413，要么卡一会儿就超时，要么传完发现文件损坏。

很多人第一反应是去改php.ini里的upload_max_filesize，甚至直接改成2G，改了还是不行。原因在于大文件上传本来就不只是PHP配置的事，它是一条从浏览器到Web服务器再到PHP解析器的完整链路，任何一层卡住，后面全白搭。这篇文章我会从链路分析、方案选型、PHP后端实现、前端Worker切片到多平台部署配置，把一套能用的示例讲透，适合被大附件折磨的后端开发，也适合正在搭网盘、OA、图床这类系统的同学参考。

1. 大文件上传失败是链路的失败，不是PHP一家的事

1.1 从一次500MB文件超时开始排查

我之前给一个OA系统的附件模块升级，现场报障是用户传一个500MB的项目演示视频，传到60%左右网页就卡住，刷新之后得重新传。第一反应是改PHP配置，把post_max_size和upload_max_filesize都调大，结果重启后问题依旧。

后来我按请求路径一层层查，才发现问题根本不在PHP。先是Nginx的access log里能看到部分请求记录，但没有一条对应的PHP访问日志，这说明请求在Nginx层就断了。再看Nginx错误日志，发现明晃晃的413 Request Entity Too Large。默认client_max_body_size只有1MB，别说是500MB，传个3MB的文件都过不去。

同类问题在不同Web服务器上表现完全不一样。Apache跑mod_php时通常没有严格的body大小限制，但如果你用的是Apache + FastCGI模块，FcgidMaxRequestLen默认值只有大约2MB，超过就直接返回500或403。Windows IIS默认限制会宽松很多，但FastCGI的ActivityTimeout、RequestTimeout往往90秒就把上传连接给掐断了。

1.2 一个上传请求实际上要突破四层限制

搞懂这件事之后，我把大文件上传需要迈过的关卡归纳成了四层，排查时按顺序查基本不会漏。

• 第一层是Web服务器层。Nginx看client_max_body_size，Apache看LimitRequestBody和FcgidMaxRequestLen，IIS看FastCGI设置里的超时时间。
• 第二层是PHP解析层。PHP接收multipart/form-data请求时，会按upload_max_filesize判断单个文件是否超限，按post_max_size判断整个请求体是否超限。任何一个超了，$_FILES或$_POST就可能变成空数组。
• 第三层是PHP超时层。max_execution_time、max_input_time会影响脚本能跑多久。大文件网络传输慢时，即便脚本逻辑本身很快，也可能在等待接收数据阶段就超时。
• 第四层容易被忽略，是反向代理层。如果PHP前面还有一层API网关、CDN或者负载均衡器，它们往往自带请求体大小和空闲超时限制。调试时只盯着后端的话，可能查半天都查不出原因。

很多人以为修改一个配置就能解决大文件上传，实际上任意一层没放开，请求就进不了PHP。这也是为什么“改了upload_max_filesize还失败”成了最常见的咨询问题。

1.3 php.ini参数之间的连带关系

PHP上传相关参数是一套小系统，调参时最容易踩的坑是只改一个不联动。下面这几个参数我的建议值是绑定在一起理解的：

如果你只是简单地把upload_max_filesize调成2G，而post_max_size还是默认的8M，那文件一超过8M整个$_POST和$_FILES都会被PHP丢弃，表现就是页面显示“未收到文件”或者$_FILES['file']['error']返回一个莫名其妙的状态码。这是最典型的新手陷阱。

2. 方案选型：分片上传为什么更适合多平台

2.1 三种方案放在一起对比

既然改配置不是万能的，那到底怎么做大文件上传更稳妥？我实际对比过三种常见思路。

第一种是“直接整文件上传 + 把所有配置调大”。实现最简单，框架里现成的move_uploaded_file就能用。但问题很明显：某个文件传了一半网络断掉只能重来，服务器内存和CPU会被大请求体瞬间打满，而且在多个平台环境下要同时调对Web服务器、代理、PHP三层配置，维护成本特别高。

第二种是“先传到一个临时目录，再用后台任务处理”。这种方式适合内网环境里的大文件落地，比如先把文件用某种方式推到服务器，再由cron或队列脚本去处理后续逻辑。但“推上来”这一步本身依然要突破Web请求的限制，而且用户上传完成后往往拿不到即时反馈，体验一般。

第三种就是我要重点写的“前端分片上传”。思路是把一个大文件在浏览器端拆成多个小分片，每个分片单独发起一个HTTP请求。即使某个分片失败，也只重传那一片，整体成功率和错误恢复能力都明显更好。它还能配合Web Worker把计算扔到后台线程，避免上传大文件时页面卡死。

在多平台环境里，分片上传还有一个隐藏优势：你不再需要把Nginx的client_max_body_size调到几GB，也不用担心IIS FastCGI因为一个几GB请求长时间占住进程导致整个站点无响应。每个请求都是10MB级别的普通请求，平台差异被分摊到几十个小请求里，反而没那么敏感了。

2.2 分片上传的整体流程

一个完整的分片上传流程基本是这样跑的：

1. 用户选择文件，前端在Web Worker中把文件按固定大小切成若干片。
2. 首次上传前，先调用一个初始化或检测接口，把文件名、大小、upload_id上报给后端，后端创建本次上传任务。
3. 前端并发上传多个分片，每个分片对应一个独立的multipart请求，请求里至少要带upload_id、分片序号、总片数。
4. 后端每收到一片，就在服务器临时目录里按upload_id建一个任务目录，把分片文件按序号落盘。
5. 所有分片都传完后，前端或后端触发合并接口，后端按序号读分片，用追加写的方式合并成完整文件。
6. 合并完成后清理临时分片，返回最终文件地址。

这个流程听起来不复杂，但很多人实现时会在“合并”这一步踩大坑，尤其是用file_get_contents把整个文件读进内存再写出来，数据一大直接内存溢出。后面我会给一段稳妥的流式合并代码。

2.3 分片大小和并发数的选择逻辑

分片大小不是一个可以随便拍脑袋的数字。我把常见分片大小和它的影响做个对照：

我一般建议取10MB到20MB。分片太小会产生大量请求，光是TCP握手和HTTP头部开销就够受的；分片太大又失去了分片的意义。并发数选择3到5个比较合适，太多并发会把服务器磁盘IO和PHP-FPM进程池打满，反而拖慢上传速度。

3. PHP后端落地：分片的接收、幂等与合并实现

3.1 先设计一个收敛的接口协议

很多示例喜欢把上传逻辑全部塞进一个接口里，我实际做的时候习惯把接口拆成两个，前端流程更清晰，后端也更好维护。

第一个是初始化任务接口POST /api/upload/init，前端上传前先把文件名和总大小发过来，后端生成一个upload_id并记录任务元数据。第二个是核心的分片接收接口POST /api/upload/chunk，用multipart/form-data提交，字段包括upload_id、index、total，以及文件字段chunk。最后一个是合并接口POST /api/upload/merge，后端收到后开始合并分片。

这里有个经验：分片接收接口里必须对upload_id做严格校验。我见过有人直接拿原始文件名做任务标识符，两个用户同时上传同名文件时，分片目录直接被互相覆盖，最后合并出来的文件损坏。upload_id我通常用uniqid()或UUID，后端再限制只允许字母、数字、下划线和短横线，从根上杜绝路径穿越。

3.2 分片接收接口核心代码

下面这段是原生PHP实现，不依赖任何框架，核心逻辑可以直接套到ThinkPHP、Laravel或者别的框架里。

php复制<?php
// upload_chunk.php
// 前端通过 multipart/form-data POST 该接口

$uploadId = $_POST['upload_id'] ?? '';
$index    = (int)($_POST['index'] ?? -1);
$total    = (int)($_POST['total'] ?? 0);

// upload_id 白名单校验，防止路径穿越
if (!preg_match('/^[A-Za-z0-9_-]{8,64}$/', $uploadId) || $index < 0 || $total <= 0) {
    http_response_code(400);
    exit(json_encode(['code' => 400, 'msg' => 'invalid params']));
}

if (!isset($_FILES['chunk'])) {
    http_response_code(400);
    exit(json_encode(['code' => 400, 'msg' => 'chunk field missing']));
}

if ($_FILES['chunk']['error'] !== UPLOAD_ERR_OK) {
    http_response_code(400);
    exit(json_encode([
        'code' => 400,
        'msg' => 'upload error code: ' . $_FILES['chunk']['error']
    ]));
}

$tmpFile = $_FILES['chunk']['tmp_name'];
if (!is_uploaded_file($tmpFile)) {
    http_response_code(400);
    exit(json_encode(['code' => 400, 'msg' => 'invalid upload file']));
}

// 每个任务一个独立目录
$taskDir = __DIR__ . '/upload_tmp/' . $uploadId;
if (!is_dir($taskDir)) {
    if (!mkdir($taskDir, 0755, true) && !is_dir($taskDir)) {
        http_response_code(500);
        exit(json_encode(['code' => 500, 'msg' => 'create dir failed']));
    }
}

// 分片文件名统一用序号，前面补零保证排序正确
$chunkFile = $taskDir . '/' . sprintf('%08d.part', $index);

if (file_exists($chunkFile)) {
    // 已存在的分片直接返回成功，实现断点续传的幂等
    exit(json_encode(['code' => 200, 'msg' => 'duplicated chunk ok']));
}

if (!move_uploaded_file($tmpFile, $chunkFile)) {
    http_response_code(500);
    exit(json_encode(['code' => 500, 'msg' => 'save chunk failed']));
}

// 更新任务元数据，方便后面合并和定时清理判断
file_put_contents(
    $taskDir . '/meta.json',
    json_encode([
        'upload_id'  => $uploadId,
        'total'      => $total,
        'updated_at' => time(),
    ])
);

echo json_encode(['code' => 200, 'msg' => 'ok']);

注意$_FILES['chunk']['error']的不同值是排查分片问题的关键线索。UPLOAD_ERR_INI_SIZE表示分片超过upload_max_filesize，UPLOAD_ERR_PARTIAL表示网络中断导致只收到部分数据。如果报这些错误，多半不是后端逻辑问题，而是PHP上传配置没跟上分片大小。

3.3 合并文件要用流式追加，别用file_get_contents

合并接口收到请求后，会扫描任务目录里的所有分片，按序号从0读到total-1，依次写入目标文件。这里最大的坑是有人图省事循环用file_put_contents($target, file_get_contents($part), FILE_APPEND)。单个分片是10MB也就罢了，如果分片是50MB甚至100MB，file_get_contents会把整个分片加载到内存，几个并发合并请求同时进来，内存就直接爆了。

正确做法是用文件流，fopen一个输出句柄，再逐个把分片流复制过去，整个过程中PHP内存占用始终只有几十KB。

php复制<?php
// upload_merge.php
$uploadId = $_POST['upload_id'] ?? '';
$total    = (int)($_POST['total'] ?? 0);

if (!preg_match('/^[A-Za-z0-9_-]{8,64}$/', $uploadId) || $total <= 0) {
    http_response_code(400);
    exit(json_encode(['code' => 400, 'msg' => 'invalid params']));
}

$taskDir  = __DIR__ . '/upload_tmp/' . $uploadId;
$finalDir = __DIR__ . '/upload_files/';
if (!is_dir($finalDir)) {
    mkdir($finalDir, 0755, true);
}

$finalFile = $finalDir . '/' . $uploadId . '.bin';

if (!is_dir($taskDir)) {
    http_response_code(404);
    exit(json_encode(['code' => 404, 'msg' => 'task not found']));
}

// 合并期间加锁，防止前端重复触发导致重复写文件
$lockFile = $taskDir . '/merge.lock';
$lockFp   = fopen($lockFile, 'c');
if (!flock($lockFp, LOCK_EX | LOCK_NB)) {
    http_response_code(409);
    exit(json_encode(['code' => 409, 'msg' => 'merge is running']));
}

// 确认所有分片都在
for ($i = 0; $i < $total; $i++) {
    $part = $taskDir . '/' . sprintf('%08d.part', $i);
    if (!file_exists($part)) {
        flock($lockFp, LOCK_UN);
        fclose($lockFp);
        http_response_code(400);
        exit(json_encode(['code' => 400, 'msg' => 'chunk missing: ' . $i]));
    }
}

$out = fopen($finalFile, 'wb');
if (!$out) {
    flock($lockFp, LOCK_UN);
    fclose($lockFp);
    http_response_code(500);
    exit(json_encode(['code' => 500, 'msg' => 'cannot create final file']));
}

for ($i = 0; $i < $total; $i++) {
    $part = $taskDir . '/' . sprintf('%08d.part', $i);
    $in   = fopen($part, 'rb');
    if (!$in) {
        fclose($out);
        flock($lockFp, LOCK_UN);
        fclose($lockFp);
        http_response_code(500);
        exit(json_encode(['code' => 500, 'msg' => 'open chunk failed']));
    }
    // 流式复制，不会把分片读进 PHP 内存
    stream_copy_to_stream($in, $out);
    fclose($in);
}

fclose($out);
flock($lockFp, LOCK_UN);
fclose($lockFp);

// 合并成功后清理临时目录
// 这里建议保留meta.json做后续审计，也可以整个目录删除，取决于你的需求
array_map('unlink', glob($taskDir . '/*.part'));
@unlink($taskDir . '/meta.json');

echo json_encode([
    'code' => 200,
    'msg'  => 'ok',
    'url'  => '/upload_files/' . $uploadId . '.bin'
]);

合并完成后别忘了校验目标文件大小是否等于所有分片大小之和。我习惯在写完分片时记录每个分片的大小，合并完后对比一下，能筛掉不少文件损坏问题。如果是最终交付给用户的文件，还要根据原始文件扩展名重命名，不要一直用upload_id当文件名。示例里用.bin是为了避开类型伪装问题，生产环境务必自己做扩展名白名单校验。

3.4 分片接口的幂等和防护细节

上传网络不稳定时，前端可能会重发同一个分片。如果后端不做幂等处理，最后一次重发的分片覆盖了之前的内容还好，万一两次内容因为某种原因不一致，合并出来的文件就是坏的。我上面的代码已经处理了这个问题：分片文件已存在时直接返回成功，不再重复写入。

防患于未然的细节还有几个。

• 每个分片接收后都校验分片大小是否符合预期。前端在上传时可以把每片的大小通知后端，后端判断实际接收的size与声明不一致就拒绝。
• upload_id不能使用自增ID，因为接口暴露后容易被遍历和恶意上传耗尽磁盘。用随机字符串或者UUID，并加上用户维度的归属校验。
• 合并接口要做总大小限制。比如业务允许最大2GB，就在init阶段记录文件总大小，合并前检查不能超过这个值，避免恶意拼接垃圾数据撑爆服务器。

4. 前端用Worker切片与并发上传的关键代码

4.1 为什么要把切片放进Web Worker

大文件切片本身不难，用File.prototype.slice就能把文件切成多个Blob。麻烦的是文件特别大之后，主线程持续进行文件读取、大小统计、状态更新，会让页面出现明显的卡顿。尤其是切片数量多到几千个时，主线程频繁创建Blob对象和触发垃圾回收，用户界面就像死了一样。

Web Worker天生适合干这件事。它运行在独立的线程里，不会阻塞DOM渲染，主线程只需要负责把File对象传给Worker，然后接收Worker汇报的进度并更新UI。

需要提醒的是，File对象虽然能被结构化克隆到Worker中，但文件数据不会重新复制一份，底层还是同一个文件引用，所以你可以放心在Worker中反复调用file.slice()，不会因为克隆把内存翻倍。

4.2 主线程代码：启动Worker并接收进度

下面这段是主线程里的基础逻辑：

javascript复制// main.js 只负责用户交互和进度展示
const fileInput = document.getElementById('file');
const startBtn = document.getElementById('startUpload');
const progressText = document.getElementById('progressText');

startBtn.addEventListener('click', () => {
    const file = fileInput.files[0];
    if (!file) {
        alert('请先选择文件');
        return;
    }

    // 生成一个全局相对唯一的 upload_id，实际项目可用后端接口下发
    const uploadId = 'task_' + Date.now() + '_' + Math.random().toString(16).slice(2);

    const worker = new Worker('upload-worker.js');
    worker.postMessage({
        uploadId,
        file,
        chunkSize: 10 * 1024 * 1024, // 10MB
        url: '/api/upload/chunk'
    });

    worker.onmessage = (event) => {
        const data = event.data;
        if (data.type === 'progress') {
            progressText.textContent = '已上传 ' + data.percent.toFixed(2) + '%';
        } else if (data.type === 'done') {
            mergeChunks(uploadId, data.total);
        } else if (data.type === 'error') {
            alert('上传失败: ' + data.message);
            worker.terminate();
        }
    };
});

function mergeChunks(uploadId, total) {
    const formData = new FormData();
    formData.append('upload_id', uploadId);
    formData.append('total', total);

    fetch('/api/upload/merge', {
        method: 'POST',
        body: formData
    })
    .then((resp) => resp.json())
    .then((res) => {
        if (res.code === 200) {
            alert('上传完成，文件地址: ' + res.url);
        } else {
            alert('合并失败: ' + res.msg);
        }
    });
}

这个版本只做串行上传或简单启动Worker，实际大文件不适合串行跑100多个请求，所以要配合并发控制。

4.3 Worker线程内的切片、并发池与上传请求

Worker里的核心做法是：收到主线程传过来的File后，先按chunkSize计算总片数，然后定义一个并发池函数，限制同时只有3到5个分片上传请求在跑。每跑完一片，就向主线程post一条进度消息。

javascript复制// upload-worker.js
self.onmessage = (event) => {
    const { uploadId, file, chunkSize, url } = event.data;
    const total = Math.ceil(file.size / chunkSize);

    // 生成上传任务列表
    const tasks = [];
    for (let i = 0; i < total; i++) {
        const