Xdebug 3.x 在 CentOS 上必须源码编译安装，因 EPEL 包滞后或不匹配；需 php-devel 等依赖，用官方 wizard 获取精准命令；配置须用 xdebug.mode = debug 等新参数，禁用所有 remote_ 前缀项，并验证 php -i 输出确认生效。
Xdebug 3.x 在 CentOS 上必须用源码编译安装，因为 EPEL 仓库里的 php-pecl-xdebug 包往往滞后、不匹配 PHP 版本，或默认禁用关键调试模式。
确认 PHP 开发环境是否就绪
源码编译依赖 phpize 和 php-config，它们属于 php-devel 包。如果缺失，./configure 会直接报错 Cannot find php-config 或提示找不到 php.h：
- 运行
phpize -v和php-config --version验证二者存在且版本与当前 PHP 一致 - 若失败，先装依赖：
yum install php-devel gcc gcc-c++ autoconf automake - 注意：PHP-FPM 和 CLI 的 PHP 版本要一致，否则编译出的
xdebug.so可能无法被 Web 模块加载
下载、编译并安装 xdebug.so
别直接下旧版 tar.gz —— Xdebug 官方 wizard（https://xdebug.org/wizard.php）才是最稳路径。它会根据你 php -i 的完整输出，精准推荐版本和编译参数：
CentOS Linux 7.9.2009是传统CentOS Linux 7的最后主要版本，也是很多企业历史服务器中仍可能遇到的系统版本。它以稳定、兼容RHEL 7生态、文档丰富和软件支持广泛著称，曾长期用于Web服务、数据库、虚拟化节点和企业内部业务系统。不过CentOS Linux 7已于2024年6月30日停止维护，现在继续使用会面临安全补丁缺失风险。该版本更适合旧业务迁移、历史环境恢复或离
- 执行
php -i > /tmp/phpinfo.txt，把文件内容粘贴到 wizard 页面 - 复制它生成的完整命令（类似：
wget https://xdebug.org/files/xdebug-3.3.1.tgz && tar -xf xdebug-3.3.1.tgz && cd xdebug-3.3.1 && phpize && ./configure --enable-xdebug && make && sudo make install） - 成功后终端会输出类似
Installing shared extensions: /usr/lib64/php/modules/—— 记住这个路径，后面配php.ini必须用对
配置 php.ini 启用 Xdebug 3.x 模式
Xdebug 3 彻底废弃了 xdebug.remote_* 系列参数，改用 xdebug.mode 统一控制功能开关。写错参数名会导致整个扩展静默失效：
- 在
/etc/php.ini或/etc/php.d/99-xdebug.ini中添加（不要用[Xdebug]小节头）： zend_extension=/usr/lib64/php/modules/xdebug.so-
xdebug.mode = debug（仅启用调试；如需覆盖率加coverage，用逗号分隔） -
xdebug.client_host = 127.0.0.1（非remote_host） -
xdebug.client_port = 9003（非 9000；PHPStorm 默认监听 9003） -
xdebug.start_with_request = yes（替代remote_autostart） - 删掉所有带
remote_前缀的旧配置项，它们在 3.x 中已被忽略
验证是否生效及常见卡点
重启服务后，只靠 php -m | grep xdebug 不够 —— 它只说明扩展加载了，不保证调试通道通。真正要看的是 php -i | grep -A5 -B5 xdebug 输出中是否有 xdebug.mode => debug 和 xdebug.client_host 等值：
- 如果
xdebug.mode显示为off，检查是否拼错单词（比如写成xdebug.mdoe），或被其他 ini 文件覆盖 - 如果
phpinfo()页面里没出现 Xdebug 区块，确认zend_extension路径是否真实存在，且 SELinux 没拦截（可临时setenforce 0测试） - PHP-FPM 用户务必重启
php-fpm，不是只重启httpd或nginx；CLI 调试则需确保php -v显示的 PHP 版本与 FPM 一致
最容易被忽略的是：Xdebug 3.x 的 xdebug.mode 是“白名单式”开关，不显式声明 debug，哪怕所有 client 参数都配对了，调试请求也进不来 IDE。
