Xdebug 3 断点失效主因是配置错误：xdebug.mode未设为debug、client_port与IDE不匹配、pathMappings路径映射错误、PHP版本/扩展/配置文件未对齐。
断点不进入，90% 是 Xdebug 3 配置项写错或没生效，而不是代码或 IDE 本身的问题。
php.ini 中 xdebug.mode 没设对，断点直接被忽略
Xdebug 3 不再用 xdebug.remote_enable，而是靠 xdebug.mode 控制功能开关。设成 develop 或空值，debug 模式根本没开，断点自然不触发。
-
xdebug.mode = debug是最低要求；如需变量查看、堆栈追踪等，可设为debug,develop -
xdebug.mode = off、develop（不含debug）、或完全没这一行 → 断点全部失效 - 用
php --ri xdebug查看输出中Mode行，必须明确显示debug
VSCode 的 launch.json 与 xdebug.client_port 不匹配
VSCode 默认监听 9003，但很多人沿用 Xdebug 2 习惯写成 9000，或在 Docker/WSL2 环境下误配为 9000 却没同步改 xdebug.client_port。
Xdebug 3.4.1 是一款功能强大的 PHP 调试扩展工具，于 2025 年 1 月 6 日正式发布。作为 Xdebug 3.4 系列的首个修复版本，3.4.1 版在继承上一版本强大功能的同时，重点解决了稳定性问题。该版本不仅修复了访问超全局变量时可能引发的程序崩溃现象，还增强了对 Windows 平台 PIE 构建机制的支持，为广大 PHP 开发者提供了更加稳定的调试环境。这一版本适合所有
-
xdebug.client_port值必须和launch.json中"port": 9003完全一致 - Docker 场景下若用
host.docker.internal作xdebug.client_host，端口仍需保持一致，不能因为 host 变了就随意换 port - 检查是否有其他进程占用了
9003：终端执行lsof -i :9003（macOS/Linux）或netstat -ano | findstr :9003（Windows）
路径映射（pathMappings）错位，Xdebug 找不到对应文件
尤其在 Docker、WSL2、MAMP 虚拟路径场景下，Xdebug 在容器/服务端看到的路径（如 /var/www/html/index.php）和 VSCode 本地打开的路径（如 C:\project\index.php）不一致，断点就“悬空”了。
- 在
launch.json的pathMappings中，左边是服务器端绝对路径，右边是本地工作区路径，顺序反了就完全失联 - MAMP 用户常见错误：
"\/Applications\/MAMP\/htdocs\/" → "${workspaceFolder}"缺少末尾斜杠或转义不全 - 用
xdebug.log查证：日志里出现File name length doesn't match with breakpoint就是路径映射失败的铁证
PHP 版本、扩展路径、配置文件三者没对齐
命令行 php -v 显示的 PHP 和 Web 服务（Apache/Nginx+PHP-FPM）跑的不是同一个版本，或者 zend_extension 指向了错误架构的 .so 文件，Xdebug 根本没加载。
- Web 端确认方式：访问
phpinfo()页面，搜索Xdebug，看模块是否列出、Loaded Configuration File路径是否是你修改的php.ini - CLI 端确认方式：运行
/Applications/MAMP/bin/php/php8.2.12/bin/php --ini（macOS MAMP）或C:\MAMP\bin\php\php8.2.12\php.exe --ini（Windows），比对配置路径 -
zend_extension必须指向当前 PHP 版本对应的正确扩展文件，例如 PHP 8.2 对应no-debug-non-zts-20220829目录下的xdebug.so
最易被忽略的是：你以为改了 php.ini，其实重启的是 CLI 的 PHP，而 Apache 或 PHP-FPM 还在读旧配置；或者改了 /etc/php/8.2/cli/php.ini，但 Web 用的是 /etc/php/8.2/apache2/php.ini。务必用 phpinfo() 看“Loaded Configuration File”那一行，别凭感觉猜。
