Xdebug 安装必须严格匹配 PHP 版本、线程安全（TS/NTS）和 SAPI 类型，使用 zend_extension 加载并分 SAPI 配置对应 ini 文件，Xdebug 4 需显式设置 xdebug.mode=debug 才启用调试。
确认 PHP 版本和 SAPI 类型再装 Xdebug
装 Xdebug 失败，八成是没对上 php -v 和 php -i | grep "Server API" 的输出。Xdebug 必须和当前 PHP 的编译版本（如 8.1、8.2）、线程安全（TS/NTS）以及 SAPI（CLI / Apache / FPM）完全匹配，缺一不可。
常见错误现象：PHP Warning: Module 'xdebug' already loaded in Unknown on line 0 或 zend_extension=/path/to/xdebug.so 加载后 php -m 不显示、phpinfo() 里没 Xdebug 区块。
- 运行
php -v看主版本号（如PHP 8.2.12） - 运行
php -i | grep -E "(Thread Safety|Server API)"，确认是否为enabled（TS）或disabled（NTS），以及 SAPI 是cli、fpm-fcgi还是apache2handler - 去 xdebug.org/download 下载对应
PHP Version + TS/NTS + SAPI的.so（Linux/macOS）或.dll（Windows）文件
加载顺序和配置位置必须严格匹配 SAPI
Xdebug 是 Zend 扩展，必须用 zend_extension 指令加载，且不能放在普通 extension= 后面；更重要的是——不同 SAPI 读取的配置文件不同，改错地方等于白配。
常见错误现象：CLI 下 php -m 能看到 Xdebug，但浏览器访问 phpinfo() 没有；或反之。
立即学习“PHP免费学习笔记（深入）”；
- CLI：只读
php.ini（php --ini查路径），加一行zend_extension=/usr/lib/php/20220829/xdebug.so - FPM：要改
www.conf中的php_admin_value[extension]或更推荐——在/etc/php/8.2/fpm/conf.d/99-xdebug.ini里写zend_extension=... - Apache：确保
LoadModule php_module后，php.ini在 Apache 的phpinfo()显示的“Loaded Configuration File”路径下 - 绝对不要在多个 ini 文件里重复加载
xdebug.so，否则报already loaded
启用远程调试前先验证基础加载和触发模式
别一上来就配 xdebug.client_host 和端口，先确保 Xdebug 本身已活，且能按预期方式触发。
常见错误现象：断点不命中、IDE 无连接日志、XDEBUG_SESSION_START=1 无效。
- 加完配置后，执行
php -m | grep xdebug和php --ri xdebug，确认输出里有Support for ZTS: disabled（或 enabled）且Status => enabled - Xdebug 4 默认关闭所有调试功能，必须显式开启：至少设
xdebug.mode=debug（不是旧版的zend_extension后跟一堆xdebug.参数） - 触发方式优先级：GET/POST 参数
XDEBUG_SESSION_START=PHPSTORM> CookieXDEBUG_SESSION=PHPSTORM> 环境变量XDEBUG_CONFIG="idekey=PHPSTORM"；注意 URL 编码问题（空格要变%20） - 如果用 CLI 调试脚本，直接加
XDEBUG_MODE=debug php script.php，不用配 client_host
Windows 下 DLL 路径和依赖容易被忽略
Windows 用户装 Xdebug 失败，往往卡在 DLL 本身或其依赖缺失，而不是配置写错。
常见错误现象：PHP Startup: Unable to load dynamic library 'php_xdebug.dll'，或加载后 Apache 直接崩溃。
- 下载的 DLL 必须和 PHP 编译器一致：VC15/VC17 对应 VS2015/VS2019，
php -i | grep "Compiler"查清楚 - DLL 文件不能放在带中文或空格的路径里（如
C:\Program Files\），建议放C:\php\ext\这类纯英文无空格路径 - 用 Dependencies 工具打开
php_xdebug.dll，检查是否提示缺失MSVCP140.dll等 VC 运行库（需安装 Microsoft Visual C++ Redistributable） - Apache 下若用线程安全版（TS），DLL 必须是 TS 版本；FPM 则必须用 NTS 版本——这点比 Linux 更敏感
php --ri xdebug 输出里的每一行，尤其是 Mode 和 Status 字段。 
