PHP 7.4 + Xdebug 3.0 可用，但必须严格匹配版本、启用xdebug.mode=debug、配置client_host/client_port为127.0.0.1/9003、正确设置路径映射，缺一则断点灰色失效。
PHP 7.4 + Xdebug 3.0 能用，但必须手动启用调试模式、配对端口、对齐路径映射——缺一不可，否则断点永远灰色。
确认Xdebug 3.0已加载且版本匹配
PHP 7.4 是 Xdebug 3 的最低支持版本，但 Xdebug 2.9.x 也能跑；混用会直接失效。运行以下命令验证：
-
php -v看 PHP 版本是否为 7.4.x（如PHP 7.4.33） -
php -m | grep xdebug确认模块存在 -
php --ini找到真正生效的php.ini路径（CLI 和 Web SAPI 常不同） - 访问
phpinfo()页面，搜索Xdebug v3.字样，不是v2.
若显示 v2.x，说明你装错了扩展：去 xdebug.org/download 用向导生成 PHP 7.4 + TS/NTS + Xdebug 3.x 的下载链接，别信“通用包”。
php.ini 中必须写的四条核心配置
Xdebug 3 彻底废弃了 xdebug.remote_* 系列旧参数，只认新命名。以下四行缺一不可，且必须写在 [xdebug] 段下（或全局）：
立即学习“PHP免费学习笔记（深入）”；
-
zend_extension=xdebug.so（Linux/macOS）或zend_extension=php_xdebug.dll（Windows）——路径要绝对准确 -
xdebug.mode=debug—— 不是develop或profile，仅此值可触发断点 -
xdebug.client_host=127.0.0.1—— Docker/WSL 用户必须改成host.docker.internal或宿主机真实 IP -
xdebug.client_port=9003—— Xdebug 3 默认端口，不是 9000；改了就得同步 IDE 配置
可选但推荐：xdebug.start_with_request=yes，避免每次手动加 ?XDEBUG_SESSION_START=PHPSTORM 参数。
IDE 中路径映射（path mapping）怎么填才不翻车
断点命中但跳到空白文件、变量全空？八成是 pathMappings 方向反了或没填。Xdebug 发送的是服务器上的绝对路径（比如 /var/www/html/index.php），IDE 必须把它“翻译”成你本地打开的路径（比如 /Users/me/project）。
- PhpStorm：Settings → PHP → Servers → 编辑对应 Server → “Path Mapping” 表格里填两列：
– File path on server：填 PHP 实际解析的路径（phpinfo()里看DOCUMENT_ROOT或SCRIPT_FILENAME）
– Absolute path on machine：填你本地项目根目录完整路径 - VS Code：
launch.json中"pathMappings"是对象，格式必须为：{ "/var/www/html": "${workspaceFolder}" }—— 左边是服务器路径，右边是本地路径，顺序不能颠倒 - Docker 场景下，如果容器内 PHP 运行在
/app，那左边必须写/app，不是宿主机的/Users/me/project
验证是否生效：开启 xdebug.log=/tmp/xdebug.log，触发一次请求，日志里出现 Resolved to /Users/me/project/index.php 才算成功。
为什么“Listening for connection”一直卡住
IDE 显示监听中，但断点就是不触发，常见硬坑就三个：
- 浏览器没发调试信号：Xdebug 3 默认不自动连接，必须靠
?XDEBUG_SESSION_START=PHPSTORM或官方Xdebug Helper插件激活（插件图标要点成绿色 Debug 模式） - 防火墙/杀毒软件拦了
9003端口（尤其 Windows Defender）—— 临时关掉试试，或手动放行 - PHP-FPM 覆盖了配置：检查
php-fpm.conf或 pool 配置里有没有php_admin_value[xdebug.mode] = off这类强制覆盖项，删掉或改成debug
CLI 脚本调试要额外加参数：php -dxdebug.mode=debug -dxdebug.client_host=127.0.0.1 -dxdebug.client_port=9003 script.php，光设 php.ini 不管用。
最易被忽略的是：PHP-FPM 配置和 CLI 的 php.ini 不是一份，Web 请求走的是 FPM 的配置，改错文件等于白配。每次改完，记得 sudo systemctl reload php7.4-fpm（或对应服务名），不是只重启 Apache/Nginx。
