php-fpm 必须监听 unix socket（如 /run/php/php8.1-fpm.sock）而非 127.0.0.1:9000，以统一本地与线上部署逻辑，避免权限、路径、selinux 等问题被掩盖，并规避端口冲突和防火墙干扰。
PHP-FPM 必须监听 Unix socket 而非 127.0.0.1:9000
本地开发环境用 127.0.0.1:9000 看似简单，但和线上 Nginx + PHP-FPM 协同方式不一致，容易掩盖权限、路径、SELinux 等真实问题。强烈建议统一使用 Unix socket（如 /run/php/php8.1-fpm.sock），它更贴近生产部署逻辑，且避免端口冲突和防火墙干扰。
检查 PHP-FPM 实际监听地址：grep "listen =" /etc/php/*/fpm/pool.d/www.conf。若看到 listen = 127.0.0.1:9000，请改为类似 listen = /run/php/php8.1-fpm.sock，并确保 listen.owner 和 listen.group 设为 www-data（Ubuntu/Debian）或 nginx（CentOS/RHEL）——这直接影响 Nginx 是否有权限 connect 到该 socket。
- 改完后执行
sudo systemctl reload php-fpm，再用ls -l /run/php/确认 socket 文件存在且属主/组匹配 - 如果 socket 路径不存在（如
/run/php/目录未创建），需在www.conf中加listen.mode = 0660并确保父目录可写 - Mac 或 Docker 环境下 socket 路径常为
/usr/local/var/run/php-fpm.sock，务必与 Nginx 配置中fastcgi_pass完全一致
Nginx location ~ \.php$ 块里 SCRIPT_FILENAME 必须动态拼接
很多配置直接硬写 fastcgi_param SCRIPT_FILENAME /var/www/html$fastcgi_script_name;，这会导致跨项目、多站点时出错。正确做法是依赖 $document_root 变量，否则一换根目录就报 “File not found”。
标准写法（必须放在 location ~ \.php$ 内）：
include fastcgi_params; fastcgi_pass unix:/run/php/php8.1-fpm.sock; fastcgi_index index.php; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
注意三点：
-
include fastcgi_params不能漏，它提供QUERY_STRING、REQUEST_METHOD等基础变量；单独写一堆fastcgi_param易遗漏 -
$document_root由root指令定义，必须和实际文件存放路径一致；比如root /home/user/project/public;，那么info.php就得放在该目录下 - 别用
fastcgi_split_path_info处理 PATH_INFO —— 除非你真需要支持/index.php/path/to/resource这类路由，否则徒增复杂度和安全隐患
PhpStorm Deployment 同步路径必须与 Nginx root 完全对齐
PhpStorm 的 SFTP 自动上传路径（Web server root URL 和 Local path）若和 Nginx 的 root 不一致，就会出现“页面能访问但调试断点不触发”或“文件明明上传了却 404”的情况。
典型错误配置：
- PhpStorm 设置本地路径为
/Users/me/project，Web root URL 填http://localhost，但 Nginxroot实际指向/var/www/html - 没启用
Upload changed files automatically to the default server，改完代码忘了手动上传 - SFTP 用户无权写入 Nginx 所在目录（尤其 CentOS 上 SELinux 默认阻止），导致上传静默失败
验证方法：在 PhpStorm 里右键文件 → Deployment → Upload to …，看是否提示成功；然后 SSH 登服务器，ls -l 确认文件时间戳已更新，且属主是 nginx 或 www-data。
调试时 Xdebug 连接失败？先关掉 PHP-FPM 的 opcache.restrict_api
PHP 8.0+ 默认开启 opcache.restrict_api = ""，但某些 Xdebug 版本（尤其 3.0+）在远程调试时会因 OPcache 检查失败而静默退出，表现为 PhpStorm 一直等待连接、浏览器页面卡住、Nginx error.log 无报错。
临时解决（开发机）：
echo "opcache.restrict_api=" >> /etc/php/*/cli/php.ini echo "opcache.restrict_api=" >> /etc/php/*/fpm/php.ini
重启服务：sudo systemctl restart php-fpm nginx。这不是安全漏洞，而是开发阶段绕过 OPcache 对调试入口的限制。线上环境必须恢复默认值或明确指定 API 路径。
其他关键点：
- Xdebug 配置中
xdebug.client_host（旧版xdebug.remote_host）必须填 PhpStorm 所在机器的 IP，不是127.0.0.1（除非 PhpStorm 和 Nginx 在同一台机器） - PhpStorm 的
Preferences → PHP → Servers里，Host填的是你访问网站用的域名/IP，Debugger port必须和xdebug.client_port一致（默认 9003） - 别在 CLI 模式下测试调试（
php -dxdebug.mode=debug script.php），它走的是不同通道，和 Web 请求无关
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
