PHP大文件上传失败？跨平台配置与分片上传实战

如果你的客户从后台传一个500M的压缩包，页面转了几圈然后弹出“上传失败”，你的第一反应是什么？我遇到过这件事，第一反应是去改 php.ini 里的 upload_max_filesize，改成 512M，结果还是失败。再改 post_max_size，还是失败。最后我发现，500M 大文件上传这件事，PHP 本身扛得住，真正的问题在于配置牵扯太多层：PHP 配置、Web 服务器配置、超时、内存、临时目录，还有 Windows 和 Linux 各自那点脾气。这篇文章就是把我在跨平台环境里处理 500M 上传踩过的坑和最终跑通的方案，原原本本梳理出来。

1. 500M上传为什么会失败：先看清PHP默认配置的真相

1.1 你遇到的现象大概率是这几种

我先说典型的失败场景。第一种是前端根本没发出去请求，比如 Nginx 直接返回 413 Request Entity Too Large，这是 Web 服务器层的锅。第二种是请求发出去，服务器也收了，但 PHP 报一个 POST Content-Length ... exceeds the limit 的警告，这是 post_max_size 卡住了。第三种是页面直接超时变成 504 或者空白页，这是执行时间超了，PHP 脚本被杀掉。第四种最阴间，文件看起来传完，但后端拿到的 $_FILES 数组是空的，或者 error 字段返回 1。

这些现象在 Windows 和 Linux 上都会出现，但触发点不完全一样。很多人只盯着 upload_max_filesize，以为改了这个就万事大吉，其实这个参数只控制单个文件的大小，旁边的 post_max_size 控制整个 POST 请求体的大小。500M 文件再加上表单里的其他字段，请求体肯定超过 500M，所以 post_max_size 必须比单文件上限更大，这是第一个容易漏的地方。

1.2 默认值下每个文件被卡在哪个环节

拉一下 PHP 默认配置，你会明白为什么 500M 上传在所有默认环境下都过不了：

你可以想象一个 500M 文件在手机上或者普通办公网络下上传，至少需要几十秒到几分钟。默认 30 秒的执行时间，连上传带处理，基本必然超时。就算你把执行时间改大，memory_limit 还盯着你，因为你很可能在业务代码里对 $_FILES['file']['tmp_name'] 做过 file_get_contents 这类操作，那就是把 500M 读进内存，128M 根本不够用。

还有一个容易忽略的点：PHP 接收上传文件后，并不是直接放到你指定的目录，而是先写入临时目录。Linux 默认是 /tmp，Windows 默认是 C:\Windows\Temp 或者 PHP 安装目录下的 upload_tmp_dir。这两个地方如果在运行时没有写权限，$_FILES 里也会出问题，甚至直接是空数组。

2. php.ini调整的完整思路：五个参数要一起改

2.1 核心参数和它们各自负责的关卡

真正稳定支持 500M 上传，php.ini 里需要动的不止一两个参数。我个人在生产环境用的这套组合：

ini复制upload_max_filesize = 512M
post_max_size = 550M
memory_limit = 256M
max_execution_time = 300
max_input_time = 300

这几个值不是瞎填的。post_max_size 留出 50M 的余量，是因为你上传表单里不可能只有一个文件字段，肯定还有文件名、业务ID、分片序号这些附带数据，如果还有多个文件同时上传，余量要更大。memory_limit 设置为 256M，不是让你把整个文件读进内存，而是给 PHP 处理请求时的中间变量留出缓冲，比如将来对上传内容做校验或者图片压缩时不会立刻爆掉。max_execution_time 和 max_input_time 设成 300 秒，是针对大文件慢速上传的场景，确保客户端网络波动时脚本还在等待。

改完配置后的验证方法很简单。在项目根目录放一个 phpinfo.php，内容只有一个函数 phpinfo();，浏览器打开后搜索这几个参数，确认它们的值已经变成新的设置。注意，php.ini 的修改不是改了就能生效，Linux 下改了文件还要 service php-fpm reload 或者重启 Apache，Windows 下改完也要重启对应服务，否则 phpinfo 里看到的还是旧值。

2.2 跨平台部署时的路径和生效验证方法

跨平台环境的第一个坑就是路径分隔符。Linux 上用 /，Windows 上用 \，PHP 很贴心地提供了 DIRECTORY_SEPARATOR 常量，但在配置文件和 Web 服务器里，你没办法处处用这个常量。我的习惯是统一用正斜杠 / 写路径，Windows 的 C:/php/uploadtmp 这种写法在 PHP 里可以正常识别，不需要转义成 C:\\php\\uploadtmp。

第二个坑是临时目录。强烈建议显式配置 upload_tmp_dir，不要依赖系统默认值：

ini复制upload_tmp_dir = "C:/php/uploadtmp"

然后确保这个目录存在，并且运行 PHP 的用户有写权限。Linux 下运行 PHP-FPM 的通常是 www-data 或者 nginx 用户，Windows 下运行 IIS 应用池的身份通常是 IIS_IUSRS，运行 Apache 的话可能是 SYSTEM 或者你手动指定的用户。目录权限不对，后面怎么做都是白搭。

提示：改完配置后，不要只依赖 phpinfo() 页面，我建议你再写一个测试脚本，手动提交一个刚超过旧限制的小文件，比如 3M，来确认新配置真的在 Web 请求层面生效了，而不只是 CLI 环境生效。CLI 和 PHP-FPM 的 php.ini 有时是两份，改错文件的概率真的不小。

3. 真正的跨平台方案：前端分片+后端合并

3.1 为什么单次请求传500M注定不可靠

配置调到位之后，500M 单次上传在局域网内可能没问题，但在公网上就是折磨。一个 500M 文件，哪怕网速稳定在 10Mbps，也要 400 多秒，中间只要断一下就得重头再来。而且很多民用路由器、反向代理、CDN 对单次请求体大小都有隐形的上限，你用本地 Nginx 测没问题，部署到客户的 Windows 服务器上就莫名失败。

所以处理大文件上传，我现在的默认答案就一个字：分片。把 500M 切成一堆 5M 的小块，逐个上传，每块之间的间隔哪怕很长也没关系，最后在后端合并。这样做的好处是，任何一个分片失败，只需要重传那个分片，不需要整个文件重来；而且每个请求体只有几兆，对 Web 服务器的压力小很多，跨平台部署时不容易触发各种隐藏限制。前端分片还可以配合 Web Worker 在后台线程里做切块和上传计算，避免在弱网环境下卡住浏览器主线程，这个在最火热的 大文件分片上传 相关实践里已经是被验证过的主流做法。

3.2 前端分片的核心实现

前端切片的思路并不复杂，核心是 JavaScript 的 File.slice() 方法。我写过一个比较简洁的版本：

javascript复制const CHUNK_SIZE = 5 * 1024 * 1024; // 5MB

function uploadLargeFile(file) {
    const totalChunks = Math.ceil(file.size / CHUNK_SIZE);
    const uploadId = Date.now().toString(36) + Math.random().toString(36).substr(2);

    for (let i = 0; i < totalChunks; i++) {
        const start = i * CHUNK_SIZE;
        const end = Math.min(start + CHUNK_SIZE, file.size);
        const chunk = file.slice(start, end);

        const formData = new FormData();
        formData.append('uploadId', uploadId);
        formData.append('index', i);
        formData.append('totalChunks', totalChunks);
        formData.append('chunk', chunk, file.name);

        uploadChunk(formData).catch(() => {
            // 失败重传当前分片，这里可以加一个重试计数
            return uploadChunk(formData);
        });
    }
}

function uploadChunk(formData) {
    return fetch('/upload.php', {
        method: 'POST',
        body: formData
    });
}

这里有三个细节值得注意。第一，uploadId 用时间戳加随机数生成，用于标识同一个文件的多个分片，避免不同用户上传同名文件时合并错乱。第二，index 从 0 开始，合并时分片顺序才不会乱。第三，每个分片都单独发一次请求，后端拿到后立即写入磁盘，不需要在内存里积压任何大文件内容。

3.3 后端接收与合并分片

后端要做的事情比前端多一点：接收分片、校验分片、记录分片、最终合并。我用的 PHP 实现大致如下：先把分片写入一个以 uploadId 命名的临时目录，目录里每个文件用分片序号命名，全部收齐之后，再按顺序合并成完整文件。

php复制$uploadId = $_POST['uploadId'];
$index = (int)$_POST['index'];
$totalChunks = (int)$_POST['totalChunks'];
$fileName = $_FILES['chunk']['name'];

$chunkDir = __DIR__ . '/storage/chunks/' . md5($uploadId);
if (!is_dir($chunkDir)) {
    mkdir($chunkDir, 0755, true);
}

$tmpName = $_FILES['chunk']['tmp_name'];
$chunkPath = $chunkDir . '/' . sprintf('%06d', $index);

if ($_FILES['chunk']['error'] !== UPLOAD_ERR_OK) {
    http_response_code(400);
    exit('chunk error: ' . $_FILES['chunk']['error']);
}

if (!move_uploaded_file($tmpName, $chunkPath)) {
    // Windows下跨磁盘时move_uploaded_file可能失败
    if (!copy($tmpName, $chunkPath)) {
        http_response_code(500);
        exit('save chunk failed');
    }
    unlink($tmpName);
}

$receivedChunks = count(glob($chunkDir . '/*'));
if ($receivedChunks === $totalChunks) {
    include 'merge.php'; // 清理临时分片并合并
}

这段代码里我把 move_uploaded_file 失败的情况做了一个 fallback：先复制再删除临时文件。这个做法在 Windows 上尤其重要，因为 PHP 的 move_uploaded_file 本质是 rename，当临时目录和目标目录不在同一个磁盘分区时，rename 会跨卷失败。Windows 经常出现 C 盘放临时目录、D 盘放业务附件的情况，不处理这个差异，分片上传会在最后一步莫名失败，而且 PHP 不一定抛异常，只是函数返回 false。

合并分片的核心逻辑，是遍历所有分片，用只读方式打开每个分片文件，把内容追加到目标文件：

php复制$finalFile = __DIR__ . '/storage/merged/' . $fileName;
$out = fopen($finalFile, 'wb');
if ($out === false) {
    http_response_code(500);
    exit('cannot create final file');
}

for ($i = 0; $i < $totalChunks; $i++) {
    $chunkPath = $chunkDir . '/' . sprintf('%06d', $i);
    $in = fopen($chunkPath, 'rb');
    if ($in === false) {
        fclose($out);
        exit('missing chunk ' . $i);
    }
    stream_copy_to_stream($in, $out);
    fclose($in);
}
fclose($out);

合并时用 stream_copy_to_stream 而不是把整个分片读进内存然后 fwrite，是为了确保即使在 PHP 内存限制很低的情况下，也能通过流式处理把 500M 文件合出来。这个函数会逐块拷贝，内存占用基本可控在 1M 以内。

4. Web服务器和PHP-FPM的配合：Nginx、Apache各自怎么改

4.1 Nginx的client_max_body_size和超时

PHP 配置改好了，前端分片也写好了，但如果你用的是 Nginx，还有一个很关键的坑：client_max_body_size。这个参数默认只有 1M，不管你 PHP 怎么改，Nginx 这层就会先拦截掉大请求。如果你还是单次上传，就必须在 server 或 location 块里把这个值调大：

nginx复制server {
    listen 80;
    server_name upload.example.com;

    client_max_body_size 600m;
    client_body_buffer_size 16k;
    client_body_timeout 300s;

    location ~ \.php$ {
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_pass 127.0.0.1:9000;
        fastcgi_read_timeout 300s;
        fastcgi_send_timeout 300s;
    }
}

client_max_body_size 我设成 600m，是考虑到如果是单次上传，500M 文件加上 multipart 头等信息，实际请求体会超过 500M。如果你已经做了前端分片，每个分片只有几兆，那这个值保持默认都无所谓，客户端不会发大请求体。但我在生产环境里仍然会把 client_max_body_size 调大，因为不能保证将来不会有人绕过分片逻辑直接提交大文件。

fastcgi_read_timeout 和 fastcgi_send_timeout 也建议同步调大。PHP-FPM 处理一个大文件合并时，如果花的时间超过默认的 60 秒，Nginx 会提前断开连接，前端看到的可能还是上传失败。这类的超时问题在日志里经常表现为 Upstream timed out，注意别被误导成 Nginx 本身的问题。

4.2 Windows下Nginx/Apache的细节差异

Windows 环境下的 Nginx 其实也能跑，但有几个细节比 Linux 麻烦。第一，Windows 版 Nginx 路径里推荐用正斜杠，配置文件里像 root html; 这种写法没问题，但如果你设置 client_body_temp_path，最好写绝对路径，并且确认对应目录有写权限。第二，Windows 的 Nginx 在处理并发请求时性能不如 Linux 稳定，大文件上传这种长连接请求一多，容易出现假死，我遇到过一次，只能重启 Nginx，后来把 worker_processes 调高才缓解。

如果你用的是 Apache，尤其是 Windows 下的 Apache，需要关注的是 LimitRequestBody。Apache 2.4 默认不限制请求体大小，但如果你的 httpd.conf 里显式设置了，比如 LimitRequestBody 0，那没问题；一旦被设置成某个具体值，比如 52428800，那 50M 以上的请求会被拒绝。另外 Apache 在 Windows 下处理上传时，临时文件写入的目录权限如果不对，也会出现 PHP $_FILES 文件字段为空的问题。

还有一个很容易被 Windows 开发者忽略的层：IIS。如果你的 PHP 跑在 Windows Server + IIS + FastCGI 上，除了 PHP 配置之外，还必须去 IIS 的站点配置里改请求限制。默认情况下，IIS 的 MaxAllowedContentLength 是 30000000 字节，也就是大约 28.6M，超过这个大小的请求直接返回 404.13。这个限制在 IIS 管理器里藏得比较深，路径是“请求筛选 > 编辑功能设置 > 请求限制”，填成 600000000（约 572M）才能放行 500M 文件。

注意：IIS 的 MaxAllowedContentLength 和部署在 Nginx/Apache 后面的 PHP 上传限制是两套互相独立的东西。只改 PHP 不改 IIS，500M 请求会被 IIS 本身挡住，PHP 甚至收不到请求；只改 IIS 不改 PHP，PHP 又会因为自身限制拒绝。这就是跨平台环境最容易栽跟头的地方——你可能把所有配置文件改了个遍，却漏了最外面那一层。

5. 实测中容易踩的坑与排查手段

5.1 上传失败但PHP没报错

我遇到过最让人抓狂的情况是：500M 文件上传后，目标目录里什么都没有，PHP 日志里也没有任何错误。后来逐个排查才发现，是临时目录写满了，磁盘空间不够。上传文件的临时文件先写进上传临时目录，如果你的分区只有几百兆空间，500M 文件写一半就满了，PHP 又不会把这个当成致命错误抛出来，只会在 $_FILES['file']['error'] 里给出一个数字。

所以排查上传问题时，第一步永远不是看配置，而是看服务器磁盘空间：

bash复制df -h

Windows 下就看 C 盘和业务盘剩余空间。这个检查成本最低，但往往能解决一大半“上传没反应”的诡异问题。

第二个容易掩盖问题的点是 PHP 错误显示。开发环境一般开着 display_errors，生产环境通常关掉了。如果关掉，PHP 的 warning 和 notice 都被吞了，上传失败原因只能看日志。我的建议是在上传脚本顶部临时打开错误输出，确认无误后再关掉：

php复制ini_set('display_errors', 1);
error_reporting(E_ALL);

5.2 内存和临时目录的坑

很多人以为 memory_limit 要大于文件大小才能处理大文件，这是个误解。PHP 接收上传文件时，文件是写到临时目录的，不会占用 PHP 进程内存，所以 512M 文件上传时不需要 memory_limit 也设为 512M。但如果你的业务逻辑里用了 file_get_contents($_FILES['file']['tmp_name'])，或者用 base64_encode 处理，那 500M 文件直接吃满内存，512M 都不一定够。正确的做法是全程用流式处理：fopen + fread/fwrite，或者 stream_copy_to_stream。

临时目录还有一个常见的问题：CentOS 上 /tmp 目录通常会被 systemd-tmpfiles 定期清理，如果你的上传脚本在清理周期内只写了一半，后续的合并可能找不到分片。所以我强烈建议把上传临时目录指到项目里自己创建的目录，既避开系统清理，也方便排查：

ini复制upload_tmp_dir = "/data/webroot/uploadtmp"

然后设置好目录权限，PHP-FPM 的运行用户必须对这个目录有读写权限，否则上传大文件时会在写入临时文件的瞬间失败。

5.3 一个通用的验证清单

最后把我每次处理 500M 大文件上传的排查顺序整理成一个清单，不管是 Linux 还是 Windows，按这个顺序过一遍，基本能定位 90% 的问题。

1. 确认 Web 服务器层：Nginx 看 client_max_body_size，Apache 看 LimitRequestBody，IIS 看 MaxAllowedContentLength。
2. 确认 PHP 层：upload_max_filesize、post_max_size、max_execution_time、max_input_time、upload_tmp_dir。
3. 确认临时目录存在且有写权限，磁盘剩余空间大于文件体积的两倍。
4. 确认业务目录有写权限，PHP-FPM 或 Apache/IIS 运行用户有权限创建文件。
5. 确认前端没有用 fetch 默认模式导致超时，必要时给 fetch 加上 AbortController 做超时重试。
6. 确认代码里没有把整个文件读进内存，所有文件操作都用流式方式。
7. 查看错误日志：/var/log/php-fpm/error.log、/var/log/nginx/error.log、Windows 事件查看器里的 IIS 日志，看有没有超时或权限相关的记录。

如果按这个清单还是找不到问题，那就再加一层抓包，用浏览器开发者工具看上传请求的响应码。413 是 Web 服务器层，500 是 PHP 运行期错误，499 是客户端提前断开了连接，200 但文件没写成——那就是代码逻辑和目录权限的问题。

我在实际处理中最深的体会是：500M 大文件上传不是某一个模块的活儿，而是从前端到 PHP、再到 Web 服务器、最终落到文件系统的整条链路。跨平台环境的复杂性在于，同样的配置在 Linux 上跑得好好的，挪到 Windows 上就多出 IIS 请求限制、磁盘分区、路径分隔符这些额外变量。与其等到上线后再被各种诡异的报错折磨，不如在动手之前就把这些差异全部列出来，一条条验证过去。分片上传配合流式合并，是我目前见过的最稳妥的方案，以后有超过 1G 的需求，我也会继续沿用这个思路。