xdebug 3.x 必须用 xdebug.mode 控制功能，旧参数如 remote_enable 失效；正确配置需确认 php 版本、扩展路径，仅需四行配置即可启用调试，端口默认 9003，避免与 php-fpm 冲突。
Xdebug 3.x 已经彻底改用 xdebug.mode 控制功能开关，旧版的 xdebug.remote_enable 等参数在 3.x 中直接失效——装了也连不上，别白折腾。
确认 PHP 版本和扩展路径再动手
装错版本的 xdebug.so 是最常见失败原因。先执行：
php -v php --ini php -m | grep xdebug
如果没输出，说明还没加载；如果有但版本太老（比如显示 Xdebug v2.9），就得卸载重来。关键点：
-
php --ini显示的 “Loaded Configuration File” 路径才是你要改的php.ini -
php -i | grep "extension_dir"能看到.so文件该放哪，比如/usr/lib/php/20220531/ - Ubuntu/Debian 用户优先用
sudo apt install php-xdebug，它自动匹配当前 PHP 版本
php.ini 里只写这 4 行就足够启动调试
Xdebug 3 的配置大幅简化，不需要一堆 remote_* 参数。在 php.ini 或 /etc/php/*/mods-available/xdebug.ini 末尾加：
[xdebug] zend_extension=xdebug.so xdebug.mode=debug xdebug.client_host=127.0.0.1 xdebug.client_port=9003
注意：
-
zend_extension必须写对路径，比如zend_extension=/usr/lib/php/20220531/xdebug.so，相对路径容易报错 -
xdebug.mode=debug是最低要求；想同时开性能分析可写debug,profile - 端口别用
9000：PHP-FPM 默认占用了，9003是 Xdebug 3 官方默认值
VS Code 或 PhpStorm 连不上的三个检查点
浏览器访问 phpinfo() 页面能看到 Xdebug 模块，不代表 IDE 就能连上。重点查：
- IDE 是否监听了
9003端口？VS Code 的launch.json里"port": 9003必须显式写死 - PHP 请求是否真带上了调试触发信号？
xdebug.start_with_request=yes才会每次请求都连；设为trigger就得手动加?XDEBUG_SESSION_START=1 - Linux 服务器上运行
ss -tuln | grep 9003，确认本地没有其他进程占着这个端口
调试时变量突然变 null 或断点不命中？先关 profiler
很多人顺手打开 xdebug.mode=debug,profile，结果发现断点跳过、变量读不出来、页面加载慢三倍。因为 profiler 会生成大量 trace 文件并阻塞 I/O。
日常调试请保持：
xdebug.mode=debug xdebug.start_with_request=trigger
这样只有你主动加 ?XDEBUG_SESSION_START=1 时才启用调试，不影响常规请求。profiler 和 coverage 功能务必单独开启、用完即关。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
