CentOS/Ubuntu编译安装Xdebug源码防踩坑全步骤【教程】-php教程-PHP中文网

xdebug 3.x 源码编译安装核心是匹配版本、用对路径、写准新参数：必须通过官方 wizard 获取精准命令，配置仅需 zend_extension、xdebug.mode=debug、client_host、client_port=9003 和 start_withrequest=yes，严禁混用 remote* 参数。

centos/ubuntu编译安装xdebug源码防踩坑全步骤【教程】

CentOS 和 Ubuntu 上源码编译安装 Xdebug，核心不是“能不能装”，而是“装对不对”——尤其 Xdebug 3.x 彻底重构了配置逻辑，沿用旧参数或错用包管理器安装，90% 会静默失效。关键在三点：匹配 PHP 版本、用对编译路径、写准新配置项。

确认 PHP 开发环境是否就绪

源码编译依赖 phpize 和 php-config，二者必须存在且版本与当前运行的 PHP 完全一致。缺失会导致 ./configure 直接报错（如 “Cannot find php-config” 或找不到 php.h）：

运行 phpize -v 和 php-config --version，输出版本号应与 php -v 一致
若命令不存在，CentOS 执行 yum install php-devel gcc gcc-c++ autoconf automake；Ubuntu 执行 apt install php-dev build-essential
特别注意：PHP-FPM 和 CLI 的 PHP 版本必须统一。若不一致（比如 CLI 是 8.2，FPM 是 8.1），编译出的 xdebug.so 可能无法被 Web 模块加载

用官方 Wizard 获取精准编译命令

别手动猜版本、别直接下 tar.gz、别信过时教程里的固定链接。Xdebug 官方 Wizard（https://www.php.cn/link/67614aacd469da7f9d611c9be60462f1）才是唯一可靠入口：

CentOS Linux 7.9.2009

CentOS Linux 7.9.2009是传统CentOS Linux 7的最后主要版本，也是很多企业历史服务器中仍可能遇到的系统版本。它以稳定、兼容RHEL 7生态、文档丰富和软件支持广泛著称，曾长期用于Web服务、数据库、虚拟化节点和企业内部业务系统。不过CentOS Linux 7已于2024年6月30日停止维护，现在继续使用会面临安全补丁缺失风险。该版本更适合旧业务迁移、历史环境恢复或离线兼容性测试。

下载

执行 php -i > /tmp/phpinfo.txt，把完整输出粘贴到 Wizard 页面
它会自动识别 PHP 版本、SAPI 类型、线程安全模式等，并生成一条完整可执行命令（例如：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.x 废弃全部 xdebug.remote_* 参数，改用 xdebug.mode 统一控制功能开关。写错名称或混用旧参数，扩展会加载但调试通道不通：

在 /etc/php.ini 或独立配置文件（如 /etc/php.d/99-xdebug.ini）中添加以下内容（不要加 [Xdebug] 小节头）：
zend_extension=/usr/lib64/php/modules/xdebug.so（路径按 Wizard 输出的实际路径填写）
xdebug.mode = debug（仅启用调试；如需代码覆盖率，写成 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_ 前缀的旧配置项（如 xdebug.remote_enable、xdebug.remote_port），它们在 3.x 中已被忽略

验证是否真正生效

重启 PHP 服务（systemctl restart php-fpm 或 systemctl restart apache2）后，不能只靠 php -m | grep xdebug 判断：

运行 php -i | grep -A5 -B5 xdebug，重点确认输出中包含 xdebug.mode => debug、xdebug.client_host => 127.0.0.1 等值
若只显示 with-xdebug 但无具体配置项，说明扩展加载了，但配置未生效（大概率是参数名写错或路径不对）
Web 环境下可访问 phpinfo() 页面，搜索 “xdebug” 查看完整配置表；CLI 下执行 php -r "echo ini_get('xdebug.mode');" 应输出 debug