Xdebug断点不触发的主因是xdebug.mode未设为debug且xdebug.start_with_request未配对；必须确认Xdebug 3已加载、xdebug.mode=debug、xdebug.start_with_request=yes，并与PhpStorm的Debug port和IDE key严格一致。
PHP 断点调试能直接看到变量值、执行路径和调用栈，比 var_dump() 看得清楚、改得快。但配置失败最常见的原因不是漏步骤，而是 Xdebug 3 和 PhpStorm 的端口/模式/触发方式没对齐——尤其是 xdebug.mode 和 xdebug.start_with_request 这两个开关没设对，断点根本不会被触发。
确认 PHP 环境已加载 Xdebug 3 扩展
别跳过这步。很多“配置好了但不进断点”的问题，根源是 PHP 根本没加载 Xdebug。
- 在项目根目录建一个
info.php，内容只有<?php phpinfo(); ?> - 浏览器访问它，Ctrl+F 搜
Xdebug—— 必须看到完整区块，且版本号是3.x（不是 2.x） - 如果没出现，检查
php.ini中zend_extension路径是否正确、文件是否存在、是否拼错扩展名（比如写成php_xdebug.dll但实际是php_xdebug-3.1.6-7.4-vc15-x86_64.dll） - 运行
php --version，输出里也应含with Xdebug v3
php.ini 中必须设对的 Xdebug 3 关键参数
Xdebug 3 的配置逻辑和 2.x 完全不同：remote_* 系列参数已废弃，用 client_* 替代；xdebug.mode 是总开关，不设就等于关着。
-
xdebug.mode=debug—— 必须显式开启调试模式（不能只靠 IDE 连接才启动） -
xdebug.start_with_request=yes—— 让每次 HTTP 请求都自动启动调试会话（开发时最省心，不用手动加?XDEBUG_SESSION_START=PHPSTORM） -
xdebug.client_host=127.0.0.1—— PhpStorm 在本机，就填这个；远程调试才填宿主机 IP -
xdebug.client_port=9003—— 推荐用9003，避开被 Docker、Laravel Sail 或其他服务占用的9000；务必和 PhpStorm 设置一致 -
xdebug.idekey=PHPSTORM—— 值要和 PhpStorm 的 DBGp Proxy 里填的一样，大小写敏感 - 删掉所有
xdebug.remote_*行（如xdebug.remote_enable），它们在 Xdebug 3 中无效，还可能报错
PhpStorm 里三处关键设置必须同步
光改 php.ini 不够，PhpStorm 的三个地方必须和它严丝合缝，否则监听开了也收不到连接。
立即学习“PHP免费学习笔记（深入）”；
-
PHP → Debug → Debug port：填和
xdebug.client_port一样的值（如9003），验证按钮点一下，看到绿色对勾才算通 -
PHP → Servers：添加一个 Server，Host 留空或填
localhost，Port 填你 Web 服务实际监听的端口（如80、8080），Debugger 选Xdebug；不要勾选 “Use path mappings”，除非你真在做远程部署 -
PHP → Debug → DBGp Proxy：IDE key 填
PHPSTORM（和php.ini里一致），Host 和 Port 可留空 —— 这个 Proxy 功能多数本地开发用不上，填了反而容易干扰
启动调试前最容易忽略的两件事
断点打上了、监听开了、URL 访问了，但 PhpStorm 就是没反应？大概率卡在这两个细节上。
-
确保 PhpStorm 处于监听状态：点击右上角那个绿色甲壳虫图标（
Start Listening for PHP Debug Connections），图标变绿且下方显示 “Listening…” 才算生效；如果它是灰色或红色，断点永远不会触发 -
浏览器没发调试请求头：Xdebug 3 默认不依赖浏览器插件，但如果你用了旧版 XdebugHelper 或手动加了
?XDEBUG_SESSION_START=PHPSTORM，请确认 URL 里确实带了这个参数；更稳的方式是直接用 PhpStorm 的Run → Debug 'xxx' (Web Page)启动，它会自动生成带 token 的 URL
真正麻烦的从来不是配置项数量，而是 Xdebug 3 的 mode 和 start_with_request 这两个布尔开关——设错一个，整个调试链就断在第一步。建议改完 php.ini 后，先用 php --ini 确认加载的是你编辑的那个文件，再跑一次 phpinfo() 看 Xdebug 区块里的 Mode 是否显示 debug，最后再碰 PhpStorm。
