PHP-FPM 处理大文件上传超时如何调整配置参数？

解决 PHP-FPM 大文件上传超时，需要同时调整 Web 服务器（Nginx/Apache）、PHP 解释器（php.ini）和 PHP-FPM 进程管理器（php-fpm.conf）三层的超时与大小限制。适用场景为上传文件超过默认 1M-2M 限制或处理时间超过 30 秒，风险边界在于过大的内存占用可能导致服务器 worker 进程阻塞。

先说结论：上传超时通常是多层配置不一致导致的，必须确保 Nginx、PHP 和 PHP-FPM 的 timeout 及 size 参数均大于实际文件需求。

先确认：检查 phpinfo() 当前生效的 upload_max_filesize 和 max_execution_time 值。
先处理：同步修改 Nginx client_max_body_size、PHP post_max_size 及 PHP-FPM request_terminate_timeout。
再验证：通过上传测试文件并观察 error.log 确认无 413 或 504 错误。

命令速用版

以下配置片段可直接用于参考，数值需根据实际文件大小调整，示例以 512M 为例。

php.ini 配置：

upload_max_filesize = 512M
post_max_size = 512M
max_execution_time = 300
max_input_time = 300
memory_limit = 256M

php-fpm 池配置（www.conf）：

request_terminate_timeout = 300

Nginx 配置：

client_max_body_size 512M;

为什么会这样

大文件上传超时本质是请求链路中任一环节的限制先于上传完成被触发。客户端发送数据经过 Web 服务器缓冲，再转发给 PHP-FPM，最后由 PHP 脚本处理，任何一层的时间或大小限制都会中断请求。

Web 服务器层（如 Nginx）默认限制请求体大小为 1M，超过直接返回 413 错误。PHP 层限制脚本执行时间和输入解析时间，超时抛出 Fatal Error。PHP-FPM 层作为进程管理器，设有硬性的 request_terminate_timeout，一旦脚本运行超过该值，FPM 会直接杀死 worker 进程，导致 502 Bad Gateway。

分步处理

按请求流向从外到内依次调整，每步修改后需重载对应服务。

1. 调整 Web 服务器限制

编辑 Nginx 配置文件（通常在 http 或 server 块），添加或修改 client_max_body_size。修改后执行 nginx -s reload。

2. 调整 PHP 解释器限制

找到 php.ini 文件，修改 upload_max_filesize 和 post_max_size。注意 post_max_size 必须大于或等于 upload_max_filesize，否则上传会失败。同时增加 max_execution_time 和 max_input_time。修改后需重启 PHP-FPM。

3. 调整 PHP-FPM 进程限制

编辑 php-fpm 池配置文件（如 www.conf），查找 request_terminate_timeout。默认值通常为 0（禁用）或跟随 php.ini，建议显式设置为大于脚本预期运行时间。修改后执行 systemctl reload php-fpm。

怎么验证是否生效

创建包含 phpinfo() 函数的测试页面，搜索 upload_max_filesize 和 max_execution_time 确认 Local Value 已变更。使用 curl 或浏览器上传超过原限制的文件，观察是否成功。

检查 Web 服务器错误日志（如 /var/log/nginx/error.log）和 PHP-FPM 日志（如 /var/log/php-fpm.log）。若出现 413 Request Entity Too Large，说明 Nginx 配置未生效。若出现 504 Gateway Time-out，说明 PHP 执行超时。若出现 502 Bad Gateway，可能是 PHP-FPM 进程被杀死。

常见坑

1. post_max_size 小于 upload_max_filesize：PHP 会拒绝接收数据，$_FILES 为空。

2. 只改了 php.ini 没改 php-fpm.conf：request_terminate_timeout 优先级更高，会强制终止脚本。

3. 内存限制不足：memory_limit 应大于 post_max_size，否则解析大 POST 数据时可能耗尽内存。

4. 多个 php.ini 存在：CLI 模式和 FPM 模式可能使用不同的配置文件，需用 phpinfo() 确认 Loaded Configuration File 路径。

常见问题

修改配置后需要重启服务器吗？

不需要重启操作系统，但必须重载 Web 服务器和重启 PHP-FPM 服务才能使配置生效。

upload_max_filesize 和 post_max_size 哪个优先？

post_max_size 优先，如果它小于上传文件大小，即使 upload_max_filesize 足够大，上传也会失败。

为什么设置了 max_execution_time 还是超时？

因为 PHP-FPM 的 request_terminate_timeout 设置了更短的限制，它会覆盖 PHP 脚本层面的设置。

参考来源

PHP.net: PHP 配置指令说明 - https://www.php.net/manual/en/ini.core.php
PHP.net: PHP-FPM 配置说明 - https://www.php.net/manual/en/install.fpm.configuration.php
Nginx.org: ngx_http_core_module - https://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size