Xdebug 的端口配置与 Nginx 服务配置是两个独立环节,问题的核心在于:Nginx 未正确转发 PHP 请求到 PHP-FPM。以下是关键点解析:
📌 根本原因
Xdebug 的工作逻辑:
- 依赖浏览器请求头
XDEBUG_SESSION
触发调试(或通过 IDE 的 "Listen for Xdebug" 按钮) - 通信默认使用端口 9003(注意:与 PHP-FPM 默认端口 9000 不同)
Nginx 配置误区:
- 单纯开放 9003 端口 ≠ 能处理 PHP 请求
- 必须为每个端口配置 PHP 解析规则(即
location ~ \.php$
段)
🔧 解决方案
在 Nginx 配置中添加端口 9003 的站点时,必须包含 PHP 解析指令:
server {
listen 9003;
server_name localhost;
root /your/php/project/path; # 替换为实际路径
location ~ \.php$ {
fastcgi_pass 127.0.0.1:9000; # 指向 PHP-FPM
fastcgi_index index.php;
include fastcgi.conf;
}
}
⚙️ 验证步骤
检查 PHP-FPM 状态:
netstat -ano | findstr :9000 # 确保 PHP-FPM 正在监听
检查 Xdebug 配置(php.ini):
[xdebug]
zend_extension=xdebug.so
xdebug.mode=debug
xdebug.client_host=127.0.0.1
xdebug.client_port=9003 # 与 VSCode 监听端口一致
验证请求流向:
- 浏览器 → Nginx (9003端口) → PHP-FPM → Xdebug → VSCode
🌈 最终结论
你的初始配置缺失了 Nginx 9003 端口的 PHP 解析规则,导致请求未被 PHP-FPM 处理。手动新增站点时补全了该配置,因此 Xdebug 被正确触发。无需纠结端口号本身,关键是要保证 Nginx 能正确将 PHP 请求转发给 PHP-FPM。