PHP断点调试需启用Xdebug远程调试模式，Xdebug 3+配置与2.x不兼容，须确认版本、正确配置php.ini路径及参数（如xdebug.mode=debug、xdebug.client_port=9003），并解决浏览器插件、防火墙和PHP-FPM覆盖等常见连接问题。
PHP 断点调试必须启用 xdebug 的远程调试（debug）模式，而非仅开启 var_dump 类调试信息；多数集成环境（如 XAMPP、WAMP、phpstudy、MAMP）默认关闭该功能，且新版 Xdebug 3+ 的配置项与旧版 2.x 完全不兼容。
确认当前 Xdebug 版本和加载状态
运行 php -v 或新建 phpinfo() 页面查看输出中是否含 Xdebug 模块及版本号。Xdebug 3 起不再使用 zend_extension="xdebug.so" 后直接写参数的方式，所有配置必须通过 php.ini 中的独立段落设置。
- 若输出显示
Xdebug v2.9.8，配置应以xdebug.开头（如xdebug.remote_enable=1） - 若显示
Xdebug v3.1.5，必须改用xdebug.mode=debug+xdebug.start_with_request=yes等新参数 - 用
php --ini确认实际生效的php.ini路径，别改错文件（CLI 和 Web SAPI 的配置文件常不同）
Xdebug 3 配置断点调试的核心参数
仅启用 xdebug.mode=debug 不足以触发断点，还需明确调试器连接方式。主流 IDE（PhpStorm、VS Code）均通过 DBGp 协议监听本地端口，Xdebug 需反向连接过去。
-
xdebug.mode=debug：启用调试模式（不是develop或profile） -
xdebug.start_with_request=yes：每次 HTTP 请求自动启动调试会话（开发时最省事） -
xdebug.client_host=127.0.0.1：指定 IDE 监听地址（Docker 环境需填宿主机 IP，不能写localhost） -
xdebug.client_port=9003：Xdebug 3 默认端口是9003（不是旧版的9000），IDE 必须同步设为9003 -
xdebug.idekey=VSCODE或PHPSTORM：与 IDE 中设置的 key 一致，用于会话匹配
zend_extension=xdebug.so xdebug.mode=debug xdebug.start_with_request=yes xdebug.client_host=127.0.0.1 xdebug.client_port=9003 xdebug.idekey=PHPSTORM
常见连不上断点的三个硬坑
90% 的“断点灰了”“没反应”问题都卡在这三处，和代码本身无关。
立即学习“PHP免费学习笔记（深入）”；
- 浏览器未带
XDEBUG_SESSION_START=PHPSTORM参数（或未安装对应插件），Xdebug 不知道该不该连 —— 推荐装官方 JetBrains IDE Helper 浏览器插件一键触发 - 防火墙/杀毒软件拦截了
9003端口（尤其 Windows Defender），需手动放行 - PHP-FPM 模式下，
php-fpm.conf或 pool 配置中覆盖了php_admin_value[xdebug.mode]，导致 ini 设置被强制重置
验证调试是否真正就绪
不要只看 phpinfo() 里有没有 Xdebug 字样，要实测连接。在 PHP 脚本开头加一行：xdebug_break();，然后启动 IDE 调试监听（PhpStorm 点 ▶️ 图标旁的虫子，VS Code 按 Ctrl+Shift+D → 启动 Listen for Xdebug），刷新页面。如果 IDE 自动停在 xdebug_break() 行，说明通了。
注意：Xdebug 3 的 xdebug_break() 是函数调用，不是注释；它不会报错，但前提是前面所有配置已生效且端口畅通。漏掉任意一环，它就静默失效 —— 这正是最让人抓狂的地方。
