PHP 上传进度一直到完成才变化是不是请求缓冲导致

是的，PHP_SESSION_UPLOAD_PROGRESS 一直停在 0，或者只有文件上传完成后才突然变成 100%，很可能是 Web 服务器先把整个请求体缓冲完，再交给 PHP。PHP 官方文档也明确提醒：请求缓冲没有关闭时，PHP 可能只能在文件完全上传后看到它。

但不要一上来只改 Nginx。上传进度的数据要经过“浏览器表单 → 请求缓冲层 → PHP SAPI → session 存储 → 轮询接口”这条链路。只要隐藏字段缺失、session 不一致、轮询被会话锁住，或者中间还有一层代理在缓存请求体，页面都会看起来像是进度失效。

官方文档：https://www.php.net/manual/en/session.upload-progress.php

Nginx FastCGI 文档：https://nginx.org/en/docs/http/ngx_http_fastcgi_module.html#fastcgi_request_buffering

先看上传进度数据会经过哪些环节

session.upload_progress 不是浏览器直接提供的百分比接口。PHP 在接收 multipart 请求时，根据表单中的进度字段，把已处理字节数和总长度写入 $_SESSION；另一个请求再读取这个 session。也就是说，PHP 必须在上传过程中持续收到请求体，轮询请求也必须拿到同一个会话。

因此，标题中的现象可以先这样判断：

• 如果 PHP 配置或隐藏字段错误，通常是进度对象根本没有生成。
• 如果 session 标识不一致，上传请求正在更新一个会话，轮询请求却读取另一个会话。
• 如果进度对象存在，但数值只在末尾跳变，优先检查 Web 服务器的请求体缓冲。

先把表单入口写对：隐藏字段必须在文件字段前

PHP 只有在 session.upload_progress.enabled 开启，并且请求中带有 session.upload_progress.name 对应的字段时，才会记录进度。官方示例还把隐藏字段放在 file 字段之前，这是 multipart 数据顺序的一部分，不要把它挪到文件字段后面。

  
  开始上传

常用的 PHP 配置可以先用下面的值确认入口是否打开。freq 决定按多少字节或百分比更新，min_freq 限制两次更新之间的最短间隔；它们只影响更新频率，不会绕过 Web 服务器的请求体缓冲。

; 开启 PHP 上传进度记录；默认通常为 1。
session.upload_progress.enabled = 1
; 读取 session 时使用的键前缀。
session.upload_progress.prefix = "upload_progress_"
; 表单隐藏字段的名称，必须和 HTML 中的 name 对应。
session.upload_progress.name = "PHP_SESSION_UPLOAD_PROGRESS"
; 每接收约 1% 的请求体更新一次进度。
session.upload_progress.freq = "1%"
; 限制两次进度更新至少间隔 1 秒，避免写 session 过于频繁。
session.upload_progress.min_freq = 1
; 上传完成后清理进度记录，保持默认的安全行为。
session.upload_progress.cleanup = 1

再读 session：轮询接口只负责查询状态

进度查询请求应当使用与上传页面相同的 session cookie，并用相同的上传标识拼出 session 键。PHP 文档中的进度对象包含 bytes_processed、content_length 和 done 等字段。查询接口不要重新上传文件，也不要把进度计算交给前端猜测。

 'invalid upload id'], JSON_UNESCAPED_UNICODE);
    exit;
}

$prefix = ini_get('session.upload_progress.prefix');
$progress = $_SESSION[$prefix . $uploadId] ?? null;
// 读完后尽早释放会话锁，避免轮询请求互相排队。
session_write_close();

header('Content-Type: application/json; charset=utf-8');
if (!is_array($progress)) {
    echo json_encode(['state' => 'waiting'], JSON_UNESCAPED_UNICODE);
    exit;
}

$total = (int) ($progress['content_length'] ?? 0);
$processed = (int) ($progress['bytes_processed'] ?? 0);
// 总长度为 0 时不除法，避免把异常请求误报成 100%。
$percent = $total > 0 ? min(100, (int) floor($processed * 100 / $total)) : 0;
echo json_encode([
    'state' => !empty($progress['done']) ? 'done' : 'uploading',
    'processed' => $processed,
    'total' => $total,
    'percent' => $percent,
], JSON_UNESCAPED_UNICODE);

如果这个接口一直返回 waiting，先排查字段名称、session cookie 和上传标识；如果它能看到对象，但 processed 长时间不增长，再继续排查请求体是否抵达 PHP。注意 cleanup=1 时，所有 POST 数据读完后进度信息会被清理，所以完成后的记录消失是正常行为，不要把它当成失败。

关键修复：关闭 Nginx 到 PHP-FPM 的请求体缓冲

Nginx 的 fastcgi_request_buffering 默认是 on。开启时，Nginx 会先从客户端读取完整请求体，再发送给 FastCGI；关闭后，请求体会在收到时立即发给 PHP-FPM。这正是 PHP 上传进度需要的边界。

location ~ \\.php$ {
    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    fastcgi_pass unix:/run/php/php-fpm.sock;

    # 让 multipart 请求体边接收边转发给 PHP-FPM。
    fastcgi_request_buffering off;
    # 上传接口需要更长的读取时间，按实际带宽和文件大小调整。
    fastcgi_read_timeout 300s;
}

这里要区分两个容易混淆的配置：

• fastcgi_request_buffering 控制客户端请求体是否先被 Nginx 读完，直接影响 PHP 何时看到上传数据。
• fastcgi_buffering 控制 PHP 响应返回给客户端时是否缓冲，主要影响响应，不是本问题的第一开关。

按数据生命周期排查：到底卡在哪一层

可以沿着输入、校验、存储、查询、异常和清理这条链路排查，而不是只盯着页面上的百分比。

如果关闭 Nginx 缓冲后仍然只在末尾变化，链路上可能还有反向代理、Ingress、网关或 CDN 在完整接收后才转发。配置要在真正承接上传请求的每一层检查；只改最外层 Nginx，不代表 PHP-FPM 已经获得流式请求体。

几个经常被误判的边界

为什么打开了 enabled 还是没有进度？

开启配置只是允许 PHP 记录进度，还需要隐藏字段存在、字段名等于 session.upload_progress.name，并且 PHP 能恢复正确 session。先看轮询接口是否能读到进度对象，再判断是否是缓冲。

为什么完成后进度记录没了？

session.upload_progress.cleanup 默认开启，所有 POST 数据读完后会清理记录。这是设计行为。若业务需要历史记录，应在上传处理完成时把结果写入自己的业务存储，而不是关闭清理长期保留 session 数据。

是不是把 fastcgi_buffering 也关掉就好了？

不一定。fastcgi_buffering 是响应方向，上传进度失真首先看请求方向的 fastcgi_request_buffering。两个配置不要因为名字相近而一起修改。

这个方案能解决断点续传吗？

不能。它只告诉你当前 multipart 上传请求已经被 PHP 接收了多少字节，适合显示单次请求的进度。断点续传需要分片、偏移校验、重试和合并策略，属于另一套上传协议。

结论：先证明 PHP 没有被挡在缓冲层后面

“上传进度一直到完成才变化”确实常常是请求缓冲造成的，但正确顺序是先确认隐藏字段和 session，再确认轮询接口能读到进度对象，最后关闭承接上传请求的 FastCGI 请求体缓冲。对 Nginx + PHP-FPM，关键配置通常是 fastcgi_request_buffering off;；不要把响应缓冲配置当成替代品，也不要因为完成后的 session 记录被 cleanup 清理就误判上传失败。