Xdebug在Linux安装失败主因是PHP版本与Xdebug不兼容或zend_extension路径错误，须先用php -v和php-config确认版本及扩展目录，再按Xdebug 3语法配置xdebug.mode=debug、client_host和9003端口，并严格校验IDE路径映射与xdebug_info()状态。
Xdebug 在 Linux 上装不起来，八成卡在 zend_extension 路径或版本不匹配上。别急着重装，先确认 PHP 版本和扩展 ABI 兼容性，再按顺序配——否则改完 php.ini 重启服务也看不到 Xdebug 模块。
查清 PHP 版本和扩展目录路径
这一步跳过，后面全白忙。Xdebug 3.x 不支持 PHP 7.1 及更早，且每个 PHP 小版本（如 8.1 vs 8.2）对应不同 ABI，.so 文件不能混用。
- 运行
php -v看主版本（如PHP 8.2.12） - 运行
php-config --version和php-config --extension-dir，确认 ABI 匹配且路径可写 - 访问
phpinfo()页面，复制全部内容粘贴到 Xdebug 官方向导，它会直接告诉你该下哪个包、怎么配
安装方式选对才省事
Ubuntu/Debian 用包管理器最稳；CentOS/RHEL 推荐 pecl；源码编译只在定制 PHP 或旧系统时必要——多数人掉坑是因为硬上源码却没注意 phpize 对应的 PHP 版本。
- Ubuntu/Debian：
sudo apt install php-xdebug，自动适配当前php包版本 - 通用（含 CentOS）：
pecl install xdebug，它会自动下载、编译、放进extension_dir - 手动编译：必须用目标 PHP 的
phpize，比如/usr/bin/phpize8.2，不是系统默认的phpize
php.ini 配置必须用 Xdebug 3 的语法
Xdebug 2 和 3 的配置项几乎全变了，沿用老教程里的 xdebug.remote_enable 这类参数会导致模块加载失败或静默失效。
linux-performance-analyzer
下载
Linux 性能分析与调优专家，覆盖 CPU、内存、磁盘 I/O、网络、内核参数、编译优化、容器/K8s。适用场景：系统卡顿/高负载、内存不足/OOM/Swap 高、CPU 异常/iowait 高。
立即学习“PHP免费学习笔记（深入）”；
- 确认启用的是
zend_extension（不是extension），值为绝对路径或文件名（如xdebug.so） - Xdebug 3 必须设
xdebug.mode=debug或xdebug.mode=develop,debug，否则远程调试不触发 -
xdebug.client_host填宿主机 IP（Docker 内调试填host.docker.internal），不是127.0.0.1（容器里连不到） - 端口默认是
9003，不是旧版的9000；IDE 里也要同步改成9003 - 加一行
xdebug.log=/tmp/xdebug.log，出问题立刻看日志，比猜强十倍
验证和 IDE 映射容易被忽略的点
php -m | grep xdebug 显示模块名 ≠ 调试能通。常见断点不命中，其实是路径映射没对上——尤其是用 VS Code 或 PhpStorm 时，本地路径和服务器路径必须严格一致。
- 在 PHP 脚本里加
xdebug_info()（Xdebug 3.1+），直接输出当前连接状态、客户端地址、模式等，比翻日志更快 - VS Code 的
launch.json中pathMappings必须精确到项目根目录，例如"\/var\/www\/html\/": "${workspaceFolder}/" - PhpStorm 里要开
Start Listening for PHP Debug Connections，且确保「Filter debug connections by IDE key」没勾选（除非你真用了xdebug.idekey） - 浏览器装 Xdebug Helper 插件，点图标切到
Debug模式，再刷新页面——这是触发调试请求的关键动作
最常被跳过的其实是 xdebug.mode 和路径映射。Xdebug 3 默认不开启任何功能，mode 不设，client_host 再对也没用；而 IDE 映射错一个字符，断点就永远灰着——这两处不动手验证，装十遍都是徒劳。
