PhpStorm调试PHP必须正确配置Xdebug 3：设xdebug.mode=debug、client_host、client_port=9003；验证php -v和php -m含Xdebug；PhpStorm需启用监听、配服务器映射、浏览器加XDEBUG_SESSION_START=PHPSTORM参数。
PhpStorm 调试 PHP 代码必须配 Xdebug，但不是装上就能用——xdebug.mode 默认是 off（PHP 8.0+），旧版用 xdebug.remote_enable，参数名、加载顺序、IDE 配置三者不匹配，90% 的“断点不命中”都卡在这儿。
确认 Xdebug 已加载且版本匹配
别只看 phpinfo() 里有没有 Xdebug 模块。先运行 php -v，输出里必须带 Xdebug 字样；再执行 php -m | grep xdebug 确认模块已启用。重点看版本：Xdebug 3.x 不兼容 PhpStorm 2019.3 之前版本，Xdebug 4 尚未发布，目前最新稳定版是 3.3.x。若用的是 Ubuntu/Debian，apt install php-xdebug 安装的往往是旧版（如 2.8），必须手动下载 3.x 的 .so 文件并指定 zend_extension 路径。
修改 php.ini 中的 Xdebug 3 关键配置
Xdebug 3 彻底重构了配置项，xdebug.remote_* 全部废弃。必须设置以下三项，缺一不可：
-
xdebug.mode=debug（不是develop或off） -
xdebug.client_host=localhost（Windows 下若用 WSL，填宿主机 IP，不是127.0.0.1） -
xdebug.client_port=9003（PhpStorm 默认监听 9003，不是旧版的 9000）
顺手加一句 xdebug.log=/tmp/xdebug.log，调试失败时直接查这个日志，比猜强十倍。
立即学习“PHP免费学习笔记（深入）”；
PhpStorm 中正确配置 Debug 和 Server
菜单栏 Run → Edit Configurations，点击左上角 + 添加 PHP Web Page。关键点有三个：
-
Server configuration必须选中已定义的本地服务器（File → Settings → Languages & Frameworks → PHP → Servers），且 Host 填的域名（如localhost）要和浏览器访问地址一致 -
Start URL写相对路径即可，比如/index.php，不要写完整 URL - 勾选
Use path mappings，把本地项目路径映射到服务器上的绝对路径（例如/var/www/html），否则断点找不到文件
启动调试前，务必点右上角电话图标旁的 Start Listening for PHP Debug Connections，这个按钮是灰色的说明监听没开，断点永远不触发。
浏览器插件与 GET 参数的配合使用
仅靠 PhpStorm 启动调试，只能调试 CLI 脚本。Web 请求必须让 Xdebug 主动连回 IDE，方法有两个：
- 安装官方 JetBrains IDE Support 浏览器插件，点击插件图标启用调试，它会自动在 URL 后追加
?XDEBUG_SESSION_START=PHPSTORM - 手动加参数也行：
http://localhost/index.php?XDEBUG_SESSION_START=PHPSTORM，但注意：参数名大小写敏感，PHPSTORM不能写成phpstorm，且必须和 PhpStorm 中 Settings → PHP → Debug → Xdebug → Ide key (session ID) 设置一致
如果用了 Nginx 或 Apache 的重写规则，确保 XDEBUG_SESSION_START 不被过滤或丢弃——某些安全配置会 strip 掉下划线开头的 query 参数。
最常被忽略的一点：Xdebug 3 默认不支持通过 XDEBUG_CONFIG 环境变量传参，所有控制逻辑必须收口到 php.ini 或运行时 ini_set（不推荐）。改完配置后，sudo systemctl restart php*-fpm 或 sudo service apache2 restart 是必须的，光重启 PhpStorm 没用。
