502错误主因是fastcgi_pass路径与PHP-FPM实际socket路径不一致，须严格匹配如unix:/run/php/php8.1-fpm.sock，同时SCRIPT_FILENAME必须用$document_root动态拼接，不可硬编码。
fastcgi_pass 路径必须和 php-fpm.sock 实际路径严格一致
很多 PHP 文件返回 502 Bad Gateway，根本原因就是 fastcgi_pass 指向的 socket 文件路径错了。PHP-FPM 的 socket 文件名带版本号，比如 PHP 7.3 是 /run/php/php7.3-fpm.sock，而 PHP 8.1 是 /run/php/php8.1-fpm.sock。Nginx 配置里写错一位（比如把 8.1 写成 81 或漏掉 -fpm），就会连不上。
验证方法很简单：
- 运行
sudo systemctl status php*-fpm看当前启用的服务名 - 查监听地址：
sudo ss -tuln | grep ':9000\|php.*sock' - 确认 socket 文件存在且可读：
ls -l /run/php/和sudo -u www-data stat /run/php/php8.1-fpm.sock
注意：如果用的是 TCP（127.0.0.1:9000），得确保 www.conf 里 listen = 127.0.0.1:9000 且没被注释，同时 listen.allowed_clients 包含 127.0.0.1。
PHP 8.1 的 pm.* 参数默认行为变了，不能照搬 7.3 配置
PHP 8.1 的 FPM 进程管理器（pm）在动态模式下引入了更激进的空闲进程回收策略。如果你从 PHP 7.3 升级上来，直接复用旧的 pm.max_children = 32、pm.start_servers = 8 等参数，可能发现服务刚启动时响应快，但高峰过后 worker 大量退出，新请求进来要等进程重建，造成短暂卡顿或 504。
立即学习“PHP免费学习笔记（深入）”；
关键差异点：
-
pm.process_idle_timeout在 8.1 中默认为10s（7.3 是0，即不回收），意味着空闲 worker 10 秒后自动销毁 -
pm.max_requests默认仍是0，但建议设为1000~5000防止内存泄漏累积（尤其用了 opcache + JIT 后） -
pm.status_path开启后，访问/status?full可看到实际活跃数，比看ps aux | grep php更准
实操建议：先用静态模式压测定基线：pm = static + pm.max_children = 16，再逐步切回 dynamic 并调高 pm.min_spare_servers（比如设为 6～8）来缓冲波动。
SCRIPT_FILENAME 必须用 $document_root，别硬编码路径
常见错误是把 fastcgi_param SCRIPT_FILENAME 写成绝对路径，比如 /var/www/html$fastcgi_script_name。这在单站点时看似能跑，但一旦加了 alias、root 动态变更或用了多个 location 块，就会导致 PHP 报 No input file specified —— 因为 PHP-FPM 拿到的路径根本不存在，或者权限不对。
正确写法永远是：
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
原因：
-
$document_root是 Nginx 根据当前location和root/alias指令实时计算出的真实磁盘路径 - 硬编码路径绕过了 Nginx 的路径解析逻辑，等于把配置耦合进 PHP 层，失去灵活性
- 在 Docker 或非标准部署中（如 root 挂载到
/app），硬编码会立刻失效
PHP 8.1 的 opcache.validate_timestamps 默认关了，开发环境要手动开
PHP 8.1 开始，opcache.validate_timestamps 默认值变为 0（即不检查 PHP 文件是否修改）。这意味着你改完 index.php，刷新页面还是旧结果——不是缓存没清，是 OPcache 根本不重新加载。
这个改动对生产有利（减少 stat 系统调用），但对开发极其不友好。解决办法只有两个：
- 开发机上，在
php.ini或 pool 的php_admin_value里显式设为1 - 或者每次改完代码手动执行：
sudo pkill -o -USR2 php-fpm（仅重启 worker，不中断连接）
别指望 opcache_reset() 函数 —— 它只对当前请求生效，且需在脚本里调用，不适合调试场景。真正要“改完即见”，就得让 OPcache 主动感知文件变化。
