如何配置Xdebug以优化PHP调试体验？

本文共计656个文字，预计阅读时间需要3分钟。

确保使用Xdebug 3时，以下代码块中的`xdebug.mode`必须显式启用，否则断点将完全无效。

为什么断点打了却没停？检查 xdebug.mode 是否包含 debug

Xdebug 3 彻底改用模式驱动机制，xdebug.remote_enable 这类旧配置已失效。最常见的情况是：PHP 启动了，Xdebug 扩展也加载了，但 IDE 就是收不到连接。 - xdebug.mode 默认值是 off，不是 debug - 单步调试必须至少包含 debug，例如：xdebug.mode=debug 或 xdebug.mode=debug,develop - 如果还用 xdebug.start_with_request=yes，得确保 debug 在 mode 里，否则该配置无效 - CLI 脚本调试需额外加 XDEBUG_MODE=debug 环境变量，不能只靠 php.ini

VS Code + PHP Debug 插件连不上？重点核对 xdebug.client_host 和端口

VS Code 的 php.debug 插件默认监听 127.0.0.1:9003，但 Xdebug 3 默认连 127.0.0.1:9000，且不自动探测 host。 - 显式设置 xdebug.client_host=127.0.0.1（Docker 容器内要用宿主机 IP，不是 localhost） - 强制指定端口：xdebug.client_port=9003，和 VS Code 的 launch.json 中 port 字段一致 - 禁用 IPv6 尝试（某些系统会优先走 ::1）：xdebug.client_host=127.0.0.1 且确保 disable_functions 没禁用 gethostbyname - 验证连接是否建立：启动调试后，在终端执行 netstat -an | grep 9003，看 VS Code 是否在 LISTEN

XDEBUG_CONFIG 环境变量在 CLI 下失效？改用 XDEBUG_MODE 和 PHP_IDE_CONFIG

老教程常教用 XDEBUG_CONFIG="idekey=VSCODE" 触发调试，但在 Xdebug 3 中，这只会设置 IDE key，不开启调试会话。 - CLI 下启动调试必须设 XDEBUG_MODE=debug（或 debug,develop） - PHP_IDE_CONFIG="serverName=localhost" 用于匹配 IDE 中的 server 配置，避免“no path mapping”警告 - idekey 已被弃用，Xdebug 3 不再读取它；VS Code 默认用 vscode 作为 idekey，无需手动传 - 多项目共用一个 IDE 时，serverName 必须和 VS Code 的 launch.json 中 pathMappings 所属的 name 完全一致

Xdebug 3 的配置粒度变细，错一个 mode、漏一个 client_host、端口不匹配，都会静默失败——没有错误日志，也没有断点响应，最容易卡在“以为配好了”的假象里。