Xdebug调试失败90%因xdebug.mode未设为debug或PHPStorm端口与xdebug.client_port不一致；需确认Xdebug已加载、mode含debug、client_host/client_port与PHPStorm Debug设置完全匹配，并勾选Can accept external connections。
Xdebug 调试在 PHPStorm 里配不起来，90% 是因为 xdebug.mode 没设对，或者 PHPStorm 的 Debug port 和 xdebug.client_port 对不上 —— 不是 Xdebug 版本问题，更不是“重启没用”这种玄学。
确认 Xdebug 已加载且版本匹配
先别急着改 PHPStorm 设置。打开终端跑：php -v，如果输出里没看到 xdebug 字样，说明扩展根本没启用；有但显示 Xdebug 3.x，就得用 xdebug.mode=debug，而不是旧版的 xdebug.remote_enable=1。
-
php --ri xdebug查看详细配置，重点核对xdebug.mode（必须含debug）、xdebug.client_host（本地开发通常为127.0.0.1）、xdebug.client_port（默认 9003，PHPStorm 默认也监听 9003） - Windows + WSL 用户注意：
xdebug.client_host得填 Windows 主机 IP（比如192.168.42.1），不能写localhost或127.0.0.1，否则连接被拒绝 - Xdebug 2 和 3 的 ini 配置差异极大，混用会导致静默失效 —— 别抄旧教程的
xdebug.remote_host，Xdebug 3 已废弃该参数
PHPStorm 的 Debug 配置必须手动对齐
PHPStorm 不会自动读取 php.ini 里的 xdebug.client_port，它只认自己设置的端口。哪怕 phpinfo() 显示 Xdebug 连接的是 9003，PHPStorm 的监听端口设成 9000，照样连不上。
- 打开
Settings > PHP > Debug，确认Debug Port和xdebug.client_port完全一致（默认都是 9003） -
Can accept external connections必须勾选，否则 PHPStorm 直接丢弃 Xdebug 的连接请求 - 如果用了 Docker 或远程服务器，
Settings > PHP > Servers里要添加对应 host，并启用Use path mappings，把容器内路径映射到本地项目路径，否则断点会“命中但不暂停”
浏览器触发调试前，先验证 IDE Key 和启动方式
断点不触发？大概率是请求根本没带 Xdebug 启动指令。Xdebug 不会自动监听所有请求，必须显式激活。
立即学习“PHP免费学习笔记（深入）”；
- 推荐用
Xdebug Helper浏览器插件（Chrome/Firefox），点击图标选择Debug，它会在 URL 后自动加?XDEBUG_SESSION_START=PHPSTORM - 确保插件里设置的 IDE Key 是
PHPSTORM（PHPStorm 默认值），且 PHPStorm 的Settings > PHP > Debug > Xdebug > IDE Key也设为PHPSTORM - 命令行调试用
export XDEBUG_CONFIG="idekey=PHPSTORM"再运行脚本，别依赖php -dxdebug.start_with_request=yes—— 这个参数在 CLI 模式下部分版本不可靠
常见“断点灰掉”或“连接超时”的真实原因
断点变空心灰色、控制台打印 Connection refused 或日志里出现 Failed to connect to client，基本可锁定网络或配置错位。
- 杀毒软件或防火墙拦截了 9003 端口 —— 临时关闭试试，尤其国内某些安全软件会主动封禁非标准端口
- PHPStorm 的
Start Listening for PHP Debug Connections按钮没点（小电话图标），它不是常驻开启的，每次调试前得手动点一下 - 多项目共用一个 PHP 解释器时，不同项目的
xdebug.mode可能互相覆盖 —— 建议用php -c /path/to/project/php.ini指定独立配置，避免全局污染
最麻烦的其实是路径映射和 IDE Key 大小写——phpstorm 和 PHPSTORM 在某些系统下不等价，映射路径少一个斜杠或字母大小写不对，断点就永远灰着。调通一次后，建议把当前有效的 php.ini 片段和 PHPStorm 的 Debug 设置截图存档，下次直接比对。
