能调试的前提是Xdebug已加载且端口连通：需验证phpinfo()中xdebug.mode=debug、xdebug.start_with_request=yes（或正确触发参数），CLI与Web的php.ini须分别确认；PhpStorm端口设为9003、勾选“Can accept external connections”并点击电话图标监听，路径映射和服务器重启同样关键。
能调试的前提是 Xdebug 已加载且端口连通，不是装了插件就自动好用——很多失败都卡在这两步。
确认 Xdebug 是否真正启用
别只看 phpinfo() 里有没有 Xdebug 模块名，得验证它是否在运行时生效：
- 创建
phpinfo.php，内容为<?php phpinfo(); ?>，浏览器访问后搜索xdebug.mode，必须显示debug（不是off或空） - 检查
xdebug.start_with_request值：设为yes才会每次请求都尝试连接 IDE；设为trigger则需手动加?XDEBUG_SESSION_START=PHPSTORM或用浏览器插件激活 - 运行
php -v，输出末尾应带with Xdebug v3.x.x—— CLI 环境和 Web SAPI（如 Apache）可能用不同 php.ini，务必确认你改的是 Web 进程加载的那个配置文件（phpinfo()页面顶部的 “Loaded Configuration File” 路径）
PhpStorm 的 Debug 端口与监听必须匹配
Xdebug 3 默认用 9003，不是旧版的 9000；PhpStorm 若仍设为 9000 就永远收不到连接：
- 进
Settings → PHP → Debug，确认Debug port是9003 - 勾选
Can accept external connections（不勾选 = 只响应本地 CLI 调试，不接 Web 请求） - 右上角点击电话图标（
Start Listening for PHP Debug Connections），图标变绿色才算真在监听 - 如果系统有防火墙或 Docker 网络隔离，确保
9003端口对 PHP 进程所在环境可达（例如 Docker 容器内 PHP 要能 ping 通宿主机的127.0.0.1:9003）
服务器路径映射出错会导致断点不命中
PhpStorm 收到调试请求时，靠路径映射把服务器上的文件路径转成本地项目路径；映射错，就找不到对应源码行：
立即学习“PHP免费学习笔记（深入）”；
- 进
Settings → PHP → Servers，添加或编辑你的服务器（如localhost） - 必须勾选
Use path mappings - 左侧填项目根目录绝对路径（如
/Users/me/project），右侧填 Web 服务器看到的对应路径（如/var/www/html或/） - 常见坑：Windows 下路径用反斜杠
\但 PhpStorm 内部处理依赖正斜杠/，建议统一用/；Docker 映射时右侧路径要和容器内document_root严格一致
触发调试的两种方式别混用
要么靠 URL 参数主动触发，要么靠浏览器插件一键开关——同时设两者反而容易失效：
- 手动触发：在浏览器地址栏加
?XDEBUG_SESSION_START=PHPSTORM（注意拼写，SESSION_START不是START_SESSION） - 插件触发：Chrome 推荐
Xdebug Helper，安装后点图标选 “Debug”，它会自动注入 Cookie 并刷新页面；首次使用需在插件设置里填 IDE key 为PHPSTORM - 别在
php.ini里设xdebug.start_with_request=yes又装插件还手动加参数——Xdebug 3 对重复触发有静默降级行为，可能直接跳过连接
最常被忽略的是：Xdebug 配置改了却没重启 Web 服务（Apache/Nginx）或 PHP-FPM 进程；以及 PhpStorm 监听开了，但服务器配置里 Debugger 没选 Xdebug ——这两个点不动，其他全对也白搭。
