Xdebug 3.x 仅需四行核心配置即可启用调试：zend_extension、xdebug.mode=debug、xdebug.start_with_request=trigger、xdebug.client_host=127.0.0.1；必须删除所有xdebug.remote_*旧参数，否则PHP启动失败或断点静默失效。
Xdebug 3.x 不需要堆砌参数，真正起作用的只有四行核心配置——多写反而容易出错，尤其混入旧版 xdebug.remote_* 参数会导致 PHP 启动失败或断点完全静默。
确认版本与路径是前提
装错版本或路径错误，四行也白配。先执行：
-
php -v看 PHP 主版本（如 8.2） -
php -i | grep "xdebug.version"确认实际加载的是 3.x（如 v3.3.2），不是 2.9.x -
php --ini找到正在使用的 php.ini 路径 -
php -i | grep "extension_dir"查扩展目录，再核对zend_extension指向的 .so/.dll 文件是否存在且 ABI 匹配（例如 PHP 8.2 对应no-debug-zts-20220829）
四行有效配置（本地直连适用）
在 php.ini 或对应版本的 conf.d/xdebug.ini 中，仅保留以下四行（删除所有含 remote_ 的旧配置）：
Xdebug 3.4.1
下载
Xdebug 3.4.1 是一款功能强大的 PHP 调试扩展工具，于 2025 年 1 月 6 日正式发布。作为 Xdebug 3.4 系列的首个修复版本，3.4.1 版在继承上一版本强大功能的同时，重点解决了稳定性问题。该版本不仅修复了访问超全局变量时可能引发的程序崩溃现象，还增强了对 Windows 平台 PIE 构建机制的支持，为广大 PHP 开发者提供了更加稳定的调试环境。这一版本适合所有
-
zend_extension=/path/to/xdebug.so（Linux/macOS 绝对路径；Windows 用双引号包裹绝对路径） -
xdebug.mode=debug（必须，启用调试功能，off或空值则不工作） -
xdebug.start_with_request=trigger（推荐：按需触发，加?xdebug_trigger=1即可启动） -
xdebug.client_host=127.0.0.1（本地 IDE 监听地址，端口默认 9003，无需额外写client_port）
验证是否生效
改完重启 PHP（CLI 或 FPM），然后运行：
-
php -m | grep xdebug—— 应显示 xdebug -
php -i | grep "xdebug.mode"—— 输出应为 debug - 访问
http://localhost/test.php?xdebug_trigger=1（页面含phpinfo()或简单 echo），同时 IDE 开启监听，看是否能停在断点
常见卡点与绕过方式
四行没错却连不上？重点查这三项：
- IDE 监听端口是否设为 9003（不是 9000）
- 浏览器请求是否带
?xdebug_trigger=1（或安装 Xdebug Helper 插件并开启） - 防火墙/杀毒软件是否拦截了 9003 端口（尤其是 Windows）
