Xdebug调试需三端对齐：PHP配置、IDE端口与IDE Key严格一致，版本差异（2.x用remote_，3.x用mode/client_）不可混用，路径映射、日志开启和浏览器触发方式均须精准配置。
能调通，但必须三端端口和 IDE Key 完全对齐，缺一不可。Xdebug 3 和 2 的配置项名、默认行为差异极大，混用必失败。
确认 Xdebug 版本并匹配 php.ini 配置
Xdebug 3（2020 年后主流）和 Xdebug 2 的 ini 配置不兼容。先执行 php --version 或查看 phpinfo() 输出里的 Xdebug 行，确认是 xdebug-3.x 还是 xdebug-2.x。
- Xdebug 3：必须用
xdebug.mode=debug，xdebug.client_host，xdebug.client_port；xdebug.remote_*系列全部失效 - Xdebug 2：必须用
xdebug.remote_enable=1，xdebug.remote_host，xdebug.remote_port；xdebug.mode不存在 - 扩展加载统一用
zend_extension（不是extension），路径要绝对且可读，比如zend_extension="/usr/lib/php/20220829/xdebug.so" - 改完
php.ini后，必须重启 PHP-FPM（sudo systemctl restart php*-fpm）和 Nginx（sudo nginx -s reload）
PhpStorm 中 Debug Port 和 IDE Key 必须与 php.ini 严格一致
PhpStorm 的监听端口不是“建议值”，而是硬性连接目标。一旦错位，连接直接被拒绝，且无明确报错提示。
- 进
Settings → Languages & Frameworks → PHP → Debug，检查Debug Port：Xdebug 3 默认是9003，Xdebug 2 默认是9000；你若在php.ini改成9001，这里也得手动改成9001 -
Settings → Languages & Frameworks → PHP → Servers里添加的 Server，其Host填localhost或你 Nginx 绑定的域名，Port填 Nginx 监听的端口（如80或8000），不是 Xdebug 端口 -
Settings → Languages & Frameworks → PHP → Debug → DBGp Proxy中的IDE key必须和php.ini里的xdebug.idekey（Xdebug 2）或xdebug.client_id（Xdebug 3.1+）值完全相同，大小写敏感，常见填PHPSTORM
断点不命中？大概率是路径映射没对上
Nginx 请求的是服务器上的文件路径（如 /var/www/html/index.php），而 PhpStorm 打开的是本地项目路径（如 /home/user/project/index.php）。Xdebug 把远程路径发给 PhpStorm，IDE 靠映射才能定位到正确文件。
立即学习“PHP免费学习笔记（深入）”；
- 进
Run → Edit Configurations → PHP Web Page，选中你的调试配置，在Server configuration下点击…进入 Server 设置 - 在
Use path mappings下勾选，然后添加映射：/var/www/html→$PROJECT_DIR$（或你实际本地项目根目录的绝对路径） - 确保 Nginx 的
root指令指向的路径，和你映射的远程路径完全一致（注意末尾斜杠、符号链接、挂载点） - 如果用 Docker 或 WSL，路径更复杂：Nginx 容器内路径、宿主机路径、PhpStorm 所在系统路径，三者需逐层映射
浏览器触发调试的两种可靠方式
别依赖“自动启动”，尤其在 Nginx 场景下，xdebug.start_with_request=yes（Xdebug 3）或 xdebug.remote_autostart=1（Xdebug 2）容易被 Nginx 缓存或超时拦截。
- 最稳：安装 Chrome 插件
Xdebug Helper，点击图标 →Debug，它会在请求 URL 自动追加?XDEBUG_SESSION_START=PHPSTORM（Key 值需和 ini 里一致） - 手动：在浏览器地址栏当前 URL 后加上
?XDEBUG_SESSION_START=PHPSTORM，回车；确保此时 PhpStorm 已点击了右上角的Start Listening for PHP Debug Connections（电话图标） - 验证是否触发：临时在 PHP 脚本开头加
die('xdebug hit');，刷新页面有输出说明请求确实进了 PHP 且 Xdebug 加载成功
最容易被忽略的是：Xdebug 3 默认关闭日志，出问题时连哪里失败都不知道。上线前务必加一行 xdebug.log="/tmp/xdebug.log" 并设好权限，否则只能靠猜。
