PHP超大附件上传进度条：三种真实进度实现方案与对比解析

做 PHP 上传功能的人，应该都经历过这么一段：功能上线没问题，然后产品过来补一刀“大附件上传加个进度条吧”。你搜一圈，复制了一段 XHR 代码，发现小文件挺好用，到了几百 MB 的视频就开始露馅——进度条要么卡在 99%，要么瞬间 100%，但页面死活不跳下一步。

这不是你的代码有问题，而是“上传进度条”这件事在 HTTP 协议层面本来就分好几个层次。尤其是 PHP 环境，前端把字节发出去了、Nginx 缓冲完了、PHP-FPM 开始接收了、文件落盘了、业务处理完了，这些时刻完全不是一回事。如果你没有意识到这一点，做的进度条只能是“看起来在动”，不是真正反映超大附件的上传状态。

这篇文章我会把 PHP 场景下做超大附件上传进度条的三条路线都拆开讲透：XHR 本地发送进度、PHP 的 session.upload_progress 方案、分片上传方案。每条线都会给可以直接抄的代码和实际会踩的坑，适合正在给 Web 系统加文件上传功能、或者已经在为“超大附件进度不准”挠头的开发者。

1. HTTP 上传进度条的底层逻辑：为什么在 PHP 里格外绕

1.1 multipart/form-data 的“一次性投入”决定了进度条的样子

先说清楚 HTTP 上传的本质。浏览器上传文件时，发的是一个 POST 请求，请求体是 multipart/form-data 格式。在这个格式里，文件内容会作为请求体的一个字段，被完整地组装进一个数据流里，然后通过 TCP 连接源源不断地发给服务器。

对 HTTP 协议本身来说，上传没有“传一半停下来”这种说法。从客户端视角看，一次上传就是一个完整的请求体发送动作；从服务端视角看，服务器必须收到完整的请求之后，才能正常解析出 $_FILES、触发业务逻辑、返回响应。也就是说，浏览器发完了、服务器响不响应，中间还隔着一大截“服务器接收和处理”的时间。

这也是上传进度条比下载进度条难做的根本原因。下载时服务器往浏览器持续吐数据，响应头里的 Content-Length 会告诉浏览器总长度，浏览器可以边收边渲染进度。上传时方向反了，是浏览器往服务器吐数据，服务器并不天然有义务在中途告诉浏览器“我收到了多少”。所以如果你想做“真实的”上传进度，必须额外想办法从服务端拿数据。

1.2 三种“上传进度”不要混淆

很多开发者对进度条的理解是单一的，实际上一个完整的上传动作里，存在三种完全不同的进度。这里用一张表格帮你理清：

这三者最大的区别，在看超大附件时尤其明显。比如用户上传一个 2GB 的视频，如果本地带宽够快，浏览器可能在 5 秒内就把数据全塞给了 Nginx，前端进度条唰地到了 100%。但 Nginx 可能还在往 PHP-FPM 转发，PHP-FPM 可能还在写临时文件；写完之后你的业务还可能要做转码、压缩、移动文件到对象存储。这些全都没结束，你告诉用户“上传完成”，用户大概率会反馈：“传完了怎么界面没反应？”

所以我建议你先想清楚一个问题：你的进度条到底要表达哪个阶段。如果只是给用户一个“网络发送中”的感知，浏览器端的 xhr.upload.onprogress 就够了。如果是要表达“服务器确实收下了文件”，那必须做服务端进度统计。如果是“文件能用了”，那还要把后续处理环节纳入进度体系。

1.3 PHP 加大附件还要过三层配置门槛

除了进度条的展示问题，PHP 本身对超大附件还有天然的硬限制。最常见的几个配置项，很多新手改了一个就以为完事了：

• upload_max_filesize：限制单个文件最大体积，默认只有 2MB。
• post_max_size：限制整个 POST 请求体体积，默认 8MB。这个值必须大于 upload_max_filesize，因为请求体里除了文件，还有文件名、其他表单字段、multipart 分隔符等额外内容。
• memory_limit：PHP 处理数组、字符串时的内存上限。虽然文件不会整体读进内存，但某些封装库或操作不当也会触雷。
• max_execution_time 和 max_input_time：上传大文件时，处理时间可能很长，默认 30 秒或 60 秒很容易触发超时。

一个典型的大附件配置可以写成这样：

ini复制upload_max_filesize = 2048M
post_max_size = 2560M
max_execution_time = 0
max_input_time = -1
memory_limit = 512M

注意我特意把 post_max_size 留出了大约 500MB 的余量。因为在表单里如果还有别的字段、或者需要把分片外的元数据一起提交，这个空间是必要的。很多人只改了 upload_max_filesize 忘了 post_max_size，结果传几十 MB 文件就报 “POST Content-Length exceeds the limit”，就是这个原因。

另外，如果 PHP 跑在 Nginx 后面，Nginx 层还有一个 client_max_body_size 限制，默认 1MB。所以你在浏览器里可能看到的是 413 Request Entity Too Large，而这个错误跟 PHP 完全没关系，是 Nginx 先拒绝了。加上反向代理、负载均衡、CDN，每一层都可能有体积限制。排查超时或失败问题，不能只看 PHP 日志，要看完整的链路配置。

2. 方案一：XHR + FormData 的本地发送进度（100MB 内够用）

2.1 前端完整实现

如果文件不算特别大，比如 100MB 以内，最快能落地的方案就是浏览器原生 XHR。核心是使用 XMLHttpRequest 的 upload 对象上的 progress 事件。

下面是一个完整的示例页面逻辑，HTML 部分只有一个文件选择框和一个进度条容器。

html复制<input type="file" id="fileInput" />
<div style="width: 320px; height: 20px; background: #eee; border-radius: 4px;">
  <div id="bar" style="width: 0%; height: 100%; background: #1a7f37; border-radius: 4px;"></div>
</div>
<span id="status"></span>

javascript复制const input = document.getElementById('fileInput');
const bar = document.getElementById('bar');
const status = document.getElementById('status');

input.addEventListener('change', function () {
  const file = this.files[0];
  if (!file) return;

  const formData = new FormData();
  formData.append('file', file);

  const xhr = new XMLHttpRequest();
  xhr.open('POST', '/upload.php', true);

  // 上传过程中的进度事件，注意是 xhr.upload
  xhr.upload.addEventListener('progress', function (e) {
    if (!e.lengthComputable) return;

    const percent = Math.round((e.loaded / e.total) * 100);
    bar.style.width = percent + '%';
    status.textContent = percent + '%';
  });

  xhr.upload.addEventListener('load', function () {
    // 这个事件表示浏览器已经把数据发出去了，但不代表后端处理完成
    status.textContent = '等待服务器处理...';
  });

  xhr.onload = function () {
    if (xhr.status === 200) {
      const result = JSON.parse(xhr.responseText);
      status.textContent = result.message || '上传成功';
    } else {
      status.textContent = '上传失败: HTTP ' + xhr.status;
    }
  };

  xhr.onerror = function () {
    status.textContent = '网络异常';
  };

  xhr.send(formData);
});

如果你项目里用的是 axios，它也封装了同样的能力，配置 onUploadProgress 回调即可：

javascript复制axios.post('/upload.php', formData, {
  onUploadProgress: function (progressEvent) {
    const percent = Math.round((progressEvent.loaded / progressEvent.total) * 100);
    // 更新 UI
  }
});

注意 status.textContent = '等待服务器处理...' 这行，我在“发送完成”事件里故意把文案切到了等待处理状态。这是为了不让用户误以为已经成功——因为这时候 PHP 可能还在收数据。

2.2 PHP 后端要做的配合

PHP 这边其实没有太多特殊逻辑，正常接收文件即可。重点在于：第一，必须提前把 upload_max_filesize 和 post_max_size 改到位；第二，接口返回一定要是干净合法的 JSON，不能有任何 warning 或额外输出。因为前端读的是 xhr.responseText，一旦 PHP 前面输出了 PHP Notice，JSON.parse 就会炸。

php复制<?php
// upload.php

header('Content-Type: application/json');

if (empty($_FILES['file'])) {
    http_response_code(400);
    echo json_encode(['ok' => false, 'message' => '没有收到文件字段']);
    exit;
}

$file = $_FILES['file'];

if ($file['error'] !== UPLOAD_ERR_OK) {
    http_response_code(400);
    echo json_encode(['ok' => false, 'message' => '文件上传错误码: ' . $file['error']]);
    exit;
}

$savePath = __DIR__ . '/storage/' . uniqid('upload_', true) . '_' . basename($file['name']);

if (!is_dir(dirname($savePath))) {
    mkdir(dirname($savePath), 0755, true);
}

if (move_uploaded_file($file['tmp_name'], $savePath)) {
    echo json_encode(['ok' => true, 'message' => '上传成功', 'path' => $savePath]);
} else {
    http_response_code(500);
    echo json_encode(['ok' => false, 'message' => '文件保存失败，请检查目录权限']);
}

如果你把 PHP 跑在 Nginx 后面，别忘了调整 Nginx 配置：

nginx复制server {
    # ...
    client_max_body_size 512M;
    # 上传大头容易超时，酌情调大
    proxy_read_timeout 300s;
    fastcgi_read_timeout 300s;
}

2.3 这套方案的短板与适用边界

XHR 进度事件在中小文件场景下很直观，但它有一个天然问题：进度只代表浏览器“把字节塞进了系统 socket 缓冲区”，服务器不一定真的收完了。在 Nginx 默认配置下，Nginx 会把请求体缓冲到本地再转给 PHP-FPM，这段时间内你的前台上传早就显示 100% 了，后端可能还在转发大文件数据。

所以这套方案的真实定位是：需求不苛刻、文件体积中等、用户能接受“界面先到 100%，服务端再处理几秒”的场景。比如后台管理系统的图片批量上传、几十 MB 的文档、课程封面视频等。

如果文件动辄几百 MB、几个 GB，还要求进度条能稳定反映服务器真实状态，那么方案一的短板会非常明显。这时候就要看下面两种方案了。

3. 方案二：PHP session.upload_progress 读服务端真实接收进度

3.1 原理：PHP 解析 multipart 时顺手记账

PHP 从 5.4 开始内置了一个上传进度功能，叫 session.upload_progress。它的思路是：当请求是 POST 且 Content-Type 是 multipart/form-data，并且请求体里包含一个字段名等于 session.upload_progress.name（默认是 PHP_SESSION_UPLOAD_PROGRESS）的隐藏字段时，PHP 会在解析请求体的过程中，持续把“已接收字节数、总字节数、文件列表”这些信息写进当前 session。

也就是说，PHP 在接收上传请求时，把进度账本记到了 session 里。前端再用另一个请求去读 session，就能看到服务端真实的接收进度。

相关配置项主要有这几个：

ini复制session.upload_progress.enabled = On
session.upload_progress.cleanup = Off
session.upload_progress.prefix = "upload_progress_"
session.upload_progress.name = "PHP_SESSION_UPLOAD_PROGRESS"
session.upload_progress.freq = "1%"
session.upload_progress.min_freq = "1"

其中 cleanup 默认是 On，含义是“上传结束后立即清理进度记录”。如果你希望进度接口在最后几次轮询里还能读到“done=true”的状态，建议开发阶段把它设为 Off，否则进度数据可能在上传完成的一瞬间就消失了。

3.2 落地：表单加隐藏字段 + 轮询进度接口

使用这套方案时，前端页面上要有一个隐藏字段，名字必须是 PHP_SESSION_UPLOAD_PROGRESS 或你自定义的其他值，并且这个字段必须出现在文件字段之前。如果你用传统表单提交，写法是这样：

html复制<form action="/upload.php" method="POST" enctype="multipart/form-data">
  <input type="hidden"
         name="<?php echo ini_get('session.upload_progress.name'); ?>"
         value="demo_upload_001" />
  <input type="file" name="file" />
  <button type="submit">开始上传</button>
</form>

如果你使用 XHR 手动拼 FormData，也要注意 append 顺序：

javascript复制const key = 'upload_' + Date.now();
const formData = new FormData();

// 这一行必须放在 append file 之前！
formData.append('PHP_SESSION_UPLOAD_PROGRESS', key);
formData.append('file', file);

const xhr = new XMLHttpRequest();
xhr.open('POST', '/upload.php', true);
xhr.send(formData);

// 同时启动轮询，每秒去 progress.php 读进度
const timer = setInterval(async () => {
  const res = await fetch('/progress.php?key=' + key, { credentials: 'include' });
  const data = await res.json();
  updateProgressBar(data.percent);
  if (data.done) clearInterval(timer);
}, 1000);

服务端接收文件的上传接口本身不需要特殊代码：

php复制<?php
// upload.php
session_start();

if (isset($_FILES['file']) && $_FILES['file']['error'] === UPLOAD_ERR_OK) {
    $saveDir = __DIR__ . '/storage/';
    if (!is_dir($saveDir)) mkdir($saveDir, 0755, true);
    $savePath = $saveDir . uniqid() . '_' . basename($_FILES['file']['name']);
    move_uploaded_file($_FILES['file']['tmp_name'], $savePath);
    echo json_encode(['ok' => true]);
} else {
    http_response_code(400);
    echo json_encode(['ok' => false]);
}

关键是进度读取接口。它的逻辑很简单：根据 key 取出 session 里的进度数组，计算百分比后返回 JSON。但我这里有一个非常重要的操作，就是尽早调用 session_write_close()，否则很容易被 session 文件锁卡死。

php复制<?php
// progress.php

$key = $_GET['key'] ?? '';
if ($key === '') {
    http_response_code(400);
    exit;
}

session_start();

$prefix = ini_get('session.upload_progress.prefix');
$fullKey = $prefix . $key;

$data = $_SESSION[$fullKey] ?? null;

if (!$data) {
    echo json_encode(['percent' => 0, 'done' => false]);
    session_write_close();
    exit;
}

$total = (int)($data['content_length'] ?? 0);
$processed = (int)($data['bytes_processed'] ?? 0);

$percent = $total > 0 ? min(100, (int)round($processed / $total * 100)) : 0;

echo json_encode([
    'percent' => $percent,
    'done' => (bool)($data['done'] ?? false),
    'bytes_processed' => $processed,
    'content_length' => $total,
    'file_name' => $data['files'][0]['name'] ?? '',
]);

// 读完立刻释放 session 锁，避免阻塞其他请求
session_write_close();

PHP 存入 session 的进度数据大概长这样，你可以把 file_name、files[0]['bytes_processed'] 都打出来看：

json复制{
  "start_time": 1700000000,
  "content_length": 123456789,
  "bytes_processed": 23456789,
  "done": false,
  "files": {
    "0": {
      "field_name": "file",
      "name": "demo.mp4",
      "tmp_name": "/tmp/phpXXXXXX",
      "error": 0,
      "done": false,
      "start_time": 1700000000,
      "bytes_processed": 23400000
    }
  }
}

3.3 为什么很多人在 Nginx + PHP-FPM 下试不成功

这是方案二最容易被忽视的坑。很多人照着 PHP 文档写了半天，发现进度接口永远返回 0 或者干脆在文件传完后突然跳到 100%，完全看不到中间状态。

原因往往不在 PHP 代码，而在 Nginx 的请求缓冲。Nginx 作为反向代理转发请求给 PHP-FPM 时，默认对 FastCGI 请求有 fastcgi_request_buffering on; 的行为。也就是说，Nginx 会先把整个 HTTP 请求体完整接收并缓冲下来，比如存到临时文件里，然后再把整个请求体转发给 PHP-FPM。PHP 接收到完整请求体时，客户端那边的上传其实早就结束了。你自然读不到“服务端接收中”的进度。

要验证这个原因很简单：在 Nginx 站点配置里关掉 FastCGI 请求缓冲，再测试一次：

nginx复制location ~ \.php$ {
    fastcgi_pass unix:/run/php/php8.2-fpm.sock;
    include fastcgi_params;
    fastcgi_request_buffering off;
}

如果你前面还有一层 Nginx 做负载均衡或者静态转发，可能还需要在对应 location 里关闭 proxy_request_buffering。但请注意，关闭缓冲意味着网络数据会直接流式进入 PHP-FPM 进程。大附件上传期间，这个 PHP-FPM worker 会被长时间占用，连接数会迅速被打满。你需要在性能与进度精确度之间做权衡。

另外还有一种老环境很实用：如果你用的是 Apache 的 mod_php 模式，就不存在这层 FastCGI 缓冲问题，session.upload_progress 跑起来会顺畅很多。

3.4 方案 B 的问题自查

如果你已经决定用 session.upload_progress，我把最常见的三个坑列一下：

• 隐藏字段顺序不对。PHP_SESSION_UPLOAD_PROGRESS 对应的字段必须出现在文件字段之前。如果放后面，PHP 解析到它时文件数据已经开始接收，进度信息就不会被登记。
• 进度查询请求没带 Session Cookie。前端轮询进度接口时要用同一个浏览器会话，否则拿不到同一个 session 文件里的数据。跨域情况下要处理 CORS 与 Cookie 携带。
• Session 锁导致查询卡住。PHP 的 session 默认有文件锁，同一时间同一个 session 只有一个脚本能写。如果 upload.php 里没有处理好锁的释放，progress.php 的 session_start() 会一直等着，进度条就不再更新。这就是我为什么在进度接口里立刻写 session_write_close()。

方案二有一个比较微妙的问题：你也看到了，它能反映的只是“传到 PHP 进程”的进度，而且 PHP 在 FastCGI 模式下是否能看到中间状态，还取决于 Nginx 的缓冲策略。到了这一步，很多项目会选择更可控的路：分片上传。

4. 方案三：分片上传，超大附件的最终解法（推荐方案）

4.1 为什么最终要回到“分片”这条路上

分片上传的思路其实跟 ASP 时代讲的无组件分块上传殊途同归：前端把一个大文件用 File.slice() 切成若干个小块，然后逐块通过独立的上传请求提交给后端。后端每收到一块就保存一块，全部收齐之后再合并成完整文件。

分片方案解决的不只是进度条：

• 绕开了 PHP 对单个 POST 请求体积的限制。每个请求只传 5MB 或 10MB，PHP 的 upload_max_filesize 只要大于分片大小即可，不用调到 2G。
• 进度天然真实。每一片上传完成后，后端确实落盘了该片，前端记录“已成功上传的字节数/总字节数”，这个数字不会像方案一那样虚高。
• 天然支持断点续传。如果某一片上传失败，重传这一片就行，不用整个文件重来。
• 方便做并发控制和取消。用户想暂停，前端只要不发后面的分片即可。

缺点是需要前后端一起配合，服务端要负责分片文件管理、顺序合并、完整性校验，复杂度比方案一高不少。

架构上通常设计三个接口：

如果你的需求只是“传完能合并成一个文件就行”，不追求断点续传，也可以