Xdebug 必须严格匹配 PHP 版本与线程安全类型，配置需用绝对路径、启用 xdebug.mode=debug、设 clientport=9003 并删除所有 remote* 旧参数，最终通过 xdebug_info() 页面验证全链路生效。
PHP 安装后 Xdebug 并不能直接用，必须手动配置 xdebug.ini（或 php.ini）并验证扩展是否加载成功。跳过验证步骤，90% 的人会卡在“断点不触发”上。
确认 PHP 版本和线程安全（TS/NTS）类型
Xdebug 必须与 PHP 的编译版本严格匹配，否则 php -v 会报 “undefined symbol” 或直接静默失败。
- 运行
php -v查看 PHP 版本（如8.2.12） - 运行
php -i | grep "Thread Safety"，输出enabled表示 TS，disabled表示 NTS - 去 xdebug.org/download 下载对应版本的
.dll（Windows）或.so（Linux/macOS）文件 - 别用 pecl install xdebug —— 它默认编译为 NTS，而 Windows XAMPP/WAMP 多为 TS
在 php.ini 中正确启用 Xdebug 扩展
新版 Xdebug（3.1+）配置项大幅简化，但旧写法（如 xdebug.remote_enable=1）会完全失效，且不报错。
zend_extension=xdebug.so xdebug.mode=debug xdebug.start_with_request=yes xdebug.client_host=127.0.0.1 xdebug.client_port=9003 xdebug.log=/tmp/xdebug.log
-
zend_extension路径必须是绝对路径（如/usr/lib/php/20220829/xdebug.so），相对路径常导致加载失败 -
xdebug.mode=debug是必需的，仅设zend_extension不会启用调试功能 -
xdebug.client_port默认是9003（Xdebug 3+），不是老版本的9000；VS Code 的launch.json也得同步改 - 删掉所有以
xdebug.remote_*开头的旧配置，它们已被废弃
验证 Xdebug 是否真正生效
光看 php -m | grep xdebug 成功不等于能调试。必须检查实际行为。
立即学习“PHP免费学习笔记（深入）”；
- 运行
php -v，应看到类似with Xdebug v3.3.2, Copyright (c) 2002-2024, by Derick Rethans - 新建
test.php，内容为，在浏览器中访问——这是唯一能确认配置全链路（加载 + 初始化 + 网络连通）的方式 - 若页面空白或报 500，检查
xdebug.log文件，常见错误包括：Failed to connect to client（IDE 未监听）、Address already in use（端口被占用） - Windows 用户注意：杀毒软件（尤其 McAfee、Bitdefender）常拦截 Xdebug 的 socket 连接，临时禁用可快速验证
最常被忽略的是 IDE 监听状态和 xdebug.mode 的组合有效性——比如设了 xdebug.mode=off 却以为只要扩展加载就能断点，或者用 PHPStorm 却忘了点右上角那个绿色电话图标（Start Listening for PHP Debug Connections）。
