Xdebug 3 在 PhpStorm 中断点调试失败，90% 源于 xdebug.mode 未含 debug 或 xdebug.client_host 配置错误；需确认扩展加载、端口为 9003、路径映射精确对齐，并合理设置 xdebug.start_with_request。
Xdebug 3 在 PhpStorm 中能正常断点调试，前提是配置项匹配、端口通畅、IDE 正确监听 —— 90% 的失败源于 xdebug.mode 设置错误或 xdebug.client_host 指向失效。
PhpStorm 调试监听没反应？先确认这三件事
PhpStorm 不触发断点，不是 IDE 坏了，而是 Xdebug 根本没连上来。常见现象包括：页面正常加载、断点灰色不可用、phpinfo() 显示 Xdebug 已加载但无调试会话。
- 运行
php -m | grep xdebug确认扩展已加载（注意大小写，输出应为xdebug，不是Xdebug） - 访问
phpinfo()页面，搜索xdebug.mode，必须包含debug（如develop,debug或debug），xdebug.remote_enable在 Xdebug 3 中已废弃，设了也无效 - 在 PhpStorm 中检查 Settings > PHP > Debug > Xdebug，确认
Debug port是9003（Xdebug 3 默认值），且勾选了 Can accept external connections
xdebug.client_host 怎么填才不连丢
这个值决定 Xdebug 向哪台机器发起调试连接。填错会导致“连接被拒绝”或静默失败，日志里只显示 Failed to connect to client。
- 本地开发（PHP 和 PhpStorm 都在本机）：填
127.0.0.1或localhost（推荐前者，更稳定） - Docker 容器中运行 PHP，宿主机运行 PhpStorm：
Windows/macOS 填host.docker.internal；Linux 填宿主机真实 IP（如192.168.1.50），不能填172.17.0.1（Docker bridge 网关地址通常不通） - 远程服务器调试（PHP 在云服务器，你在本地连）：填你本机的公网/局域网 IP，并确保该 IP 对服务器可达，且防火墙放行
xdebug.client_port（默认9003）
PhpStorm 断点不生效？检查路径映射是否对齐
即使连接成功，断点仍可能灰掉 —— 这是 PhpStorm 找不到对应文件的典型表现。Xdebug 发送的是服务端绝对路径（如 /var/www/html/index.php），而 PhpStorm 打开的是本地路径（如 /Users/me/project/index.php），二者必须映射一致。
立即学习“PHP免费学习笔记（深入）”；
- 在 PhpStorm 中打开 Run > Edit Configurations > PHP Remote Debug
- 点击 Server configuration > ...，进入 Path Mappings
- 左侧填服务器上的项目根路径（如
/var/www/html），右侧填你本地项目根目录（如/Users/me/project） - 如果用 Docker，服务器路径要和
docker run -v挂载路径完全一致；路径末尾斜杠有无必须统一（建议都带/）
调试启动后卡住或超时？别忽略 xdebug.start_with_request 的取值
设成 yes 会让每个请求都尝试连 IDE，一旦 PhpStorm 没在监听，脚本就卡在连接阶段（默认超时 200ms，但感知明显）。这不是 bug，是设计行为。
- 日常开发建议用
trigger：xdebug.start_with_request = trigger，然后通过 URL 加参数启动调试，例如：http://localhost/app.php?XDEBUG_SESSION_START=PHPSTORM - 确保 PhpStorm 的 Start Listening for PHP Debug Connections 按钮已点亮（绿色电话图标）
- 如果用 CLI 脚本调试，需额外加环境变量：
XDEBUG_CONFIG="idekey=PHPSTORM" php script.php，且idekey必须与 PhpStorm 中 Settings > PHP > Debug > Xdebug > IDE key 一致（默认是PHPSTORM）
最易被忽略的是路径映射的精确性 —— 多一个空格、少一个斜杠、大小写不一致，都会让断点彻底失效。与其反复重启服务，不如先在 phpinfo() 里逐字核对 xdebug.mode 和 xdebug.client_host 的输出值，再打开 xdebug.log 看第一行连接尝试是否成功。
