Xdebug不生效主因是配置错位、版本不兼容、配置项过时、端口不一致或变量显示关闭。需核对CLI/Web的php.ini路径、用xdebug.org/wizard匹配版本、改用Xdebug 3配置语法、确保IDE端口与xdebug.client_port一致，并启用xdebug.show_local_vars=1。
Xdebug安装后不生效，90%的情况不是没装上，而是配置没对齐环境或版本错位。
php.ini 文件用错了位置
PHP CLI（命令行）和 Web 服务器（如 Apache/Nginx + PHP-FPM）通常加载完全不同的 php.ini 文件。改了其中一个，另一个根本看不到。
- 查 CLI 用的配置：运行
php --ini，重点看Loaded Configuration File行 - 查 Web 用的配置：建个
info.php，内容为<?php phpinfo(); ?>，浏览器访问后搜索Loaded Configuration File - 调试 Web 请求时，必须改 Web 环境对应的
php.ini；用php -f script.php调试时，才需改 CLI 的php.ini
Xdebug 版本与 PHP 不兼容
比如 PHP 8.2 安装了 Xdebug 3.1.x 就可能直接静默失败——扩展加载失败时，php -m 不会报错，但 xdebug 就不会出现在列表里。
Xdebug 3.4.1
下载
Xdebug 3.4.1 是一款功能强大的 PHP 调试扩展工具，于 2025 年 1 月 6 日正式发布。作为 Xdebug 3.4 系列的首个修复版本，3.4.1 版在继承上一版本强大功能的同时，重点解决了稳定性问题。该版本不仅修复了访问超全局变量时可能引发的程序崩溃现象，还增强了对 Windows 平台 PIE 构建机制的支持，为广大 PHP 开发者提供了更加稳定的调试环境。这一版本适合所有
- 执行
php -v确认 PHP 版本和 ZTS（线程安全）状态 - 访问
https://xdebug.org/wizard，把phpinfo()页面源码粘贴进去，它会明确告诉你该下哪个.dll或.so文件 - Windows 下注意 VC 编译器版本（VC15/VC17）、架构（x86/x64）；macOS/Linux 下注意是否启用了 ZTS
Xdebug 3+ 的配置项已彻底改名
还在用 xdebug.remote_enable？那说明你套的是 Xdebug 2 的配置模板，Xdebug 3 已废弃所有 remote_* 前缀，不兼容就等于没配。
- 必须用
xdebug.mode = debug（启用调试）或xdebug.mode = develop（含错误增强） - 触发方式改用
xdebug.start_with_request = yes或trigger，而不是remote_autostart - 连接目标改用
xdebug.client_host和xdebug.client_port，旧的remote_host/remote_port被忽略 - 验证是否生效：在代码中调用
xdebug_info()，它会输出当前实际生效的所有配置
IDE 监听端口与 Xdebug 连接端口不一致
哪怕 Xdebug 配置全对，只要 IDE 没在监听同一端口，连接就会被拒绝——而且往往没有任何明显报错。
- 确认
xdebug.client_port（如9003）和 IDE 的 Debug 设置里 “Debug port” 完全一致 - PhpStorm：Settings → Languages & Frameworks → PHP → Debug → Xdebug → Debug port
- VS Code：检查
launch.json中port字段（用于listen模式），且确保没被系统防火墙拦截 - 快速验证连通性：
telnet 127.0.0.1 9003，如果提示 “Connection refused”，说明 IDE 没在监听或被拦截
最容易被忽略的一点：Xdebug 3 默认关闭了 xdebug.show_local_vars，导致断点停住后变量面板空空如也——这不是没连上，是显示被关了。加一行 xdebug.show_local_vars = 1 才能看到函数内所有变量。
