Xdebug 远程调试失败主因是服务端未启用 debug 模式，需确认 xdebug.mode=debug、xdebug.client_host 为本地 IP、xdebug.start_with_request=trigger，并检查 PhpStorm 监听端口、防火墙、Docker 端口映射及浏览器插件触发。
PHP 远程调试连不上 Xdebug？先确认 xdebug.mode 是 debug
很多连不上根本不是 PhpStorm 配置问题，而是 PHP 服务端 Xdebug 没真正启用。PHP 8.0+ 默认用 xdebug.mode 控制行为，develop 或 off 都不会触发调试连接。
- 检查
phpinfo()输出里xdebug.mode的值，必须是debug（可加develop，如debug,develop） -
xdebug.start_with_request推荐设为trigger，避免全量请求都尝试连 PhpStorm - 远程服务器上别漏掉
xdebug.client_host（旧版叫xdebug.remote_host），它得填你本地机器的 IP，不是localhost—— 容器或云服务器里尤其容易错 - 如果走 SSH 端口转发，
xdebug.client_port要和本地监听端口一致，默认是9003，但 PhpStorm 新项目默认可能设成9000，不匹配就静默失败
PhpStorm 的 Start Listening for PHP Debug Connections 按了没反应？
按钮亮了不代表真在监听；它只管本地端口，不管 Xdebug 是否发来连接。常见假阳性：
- 防火墙/安全组拦了
9003（或你自定义的端口），Mac 上系统防火墙默认会弹窗询问，Linux/Windows 服务器上常被忽略 - 多个 PhpStorm 实例同时运行，只有一个能绑定端口，另一个会“看似开启”实则监听失败
- 用了 Docker Compose 启动 PHP，但没把
9003映射到宿主机：ports: - "9003:9003"缺一不可 - 浏览器插件（如 Xdebug Helper）没点“Debug”图标，或 Cookie
XDEBUG_SESSION_START=PHPSTORM没带上 ——xdebug.start_with_request=trigger时这是唯一触发方式
断点打在 CLI 脚本里不命中？php -dxdebug.mode=debug script.php 才有效
CLI 模式下，Xdebug 不读 php.ini 里的配置（除非显式指定 ini 文件），也不会自动加载 .user.ini 或 php-fpm.conf 里的设置。
- 临时调试：直接命令行加参数，比如
php -dxdebug.mode=debug -dxdebug.client_host=10.0.2.2 script.php - 持久化：用
php --ini找到 CLI 专用的配置路径，往对应php.ini里写 Xdebug 配置 - 注意
xdebug.client_host值：Docker 宿主机是host.docker.internal（Mac/Win），Linux 上得用宿主机真实 IP - CLI 下不走浏览器 Cookie，所以
xdebug.start_with_request=trigger失效，必须设为yes或靠命令行参数强制开启
调试时变量显示 Cannot evaluate expression？关掉 Enable 'Break at first line in PHP scripts'
这个选项在「Preferences > PHP > Debug」里，看着方便，实际是调试器陷阱。它会让 Xdebug 在入口文件第一行就中断，此时 Autoloader、Composer、框架初始化都还没跑，$this、$container、$_SERVER 等全局上下文极不稳定，表达式求值直接报错。
立即学习“PHP免费学习笔记（深入）”；
- 只在真正需要跟踪启动流程时打开它，平时建议关闭
- 替代方案：在你关心的类构造函数或路由分发前手动打一个断点，更可控
- 如果已卡住，点 PhpStorm 工具栏的
Stop（红色方块），再点Resume Program（绿色三角），通常能恢复上下文 - 某些 Laravel/Symfony 项目还会因 OpCache 导致断点偏移，开发环境建议关掉
opcache.enable
调试最难的从来不是配通，而是当断点命中的那一刻，你是否清楚当前执行栈里每个变量的真实生命周期——尤其是跨进程、跨容器、跨协议时，xdebug.client_host 和 xdebug.client_port 这两个值，抄错一位，后面所有操作都是在验证“为什么不行”。
