php -dxdebug.mode=debug 没效果，因Xdebug 3需同时满足三要素：mode仅允许调试，不触发连接；必须显式设xdebug.start_with_request=yes并确保client_host可达、IDE监听对应端口（如9003）。

php -dxdebug.mode=debug 为什么没效果

直接在命令行加 -dxdebug.mode=debug 不会触发调试连接，因为 Xdebug 3 的调试行为不仅取决于 mode，还依赖 xdebug.start_with_request 和客户端连通性。单纯设 mode 只是“允许调试”，不等于“发起连接”。

CLI 调试必须显式传入启动开关

要在 CLI 下临时启用完整调试流程（即让 PHP 主动连 VS Code / PhpStorm），得同时指定 mode 和启动策略：

Xdebug 3.4.1

Xdebug 3.4.1 是一款功能强大的 PHP 调试扩展工具，于 2025 年 1 月 6 日正式发布。作为 Xdebug 3.4 系列的首个修复版本，3.4.1 版在继承上一版本强大功能的同时，重点解决了稳定性问题。该版本不仅修复了访问超全局变量时可能引发的程序崩溃现象，还增强了对 Windows 平台 PIE 构建机制的支持，为广大 PHP 开发者提供了更加稳定的调试环境。这一版本适合所有

下载

• php -dxdebug.mode=debug -dxdebug.start_with_request=yes script.php
• 或者更稳妥地补上端口和 host：php -dxdebug.mode=debug -dxdebug.start_with_request=yes -dxdebug.client_port=9003 -dxdebug.client_host=127.0.0.1 script.php
• 如果用的是 Docker 容器内调 CLI，xdebug.client_host 得换成宿主机网关，比如 host.docker.internal 或 172.17.0.1

环境变量方式更干净，也支持多模式

用 XDEBUG_MODE 环境变量比 -d 参数更推荐，尤其要同时开 debug 和 develop（比如想让 var_dump() 格式化输出）：

• XDEBUG_MODE=debug,develop php script.php
• XDEBUG_MODE=debug php -dxdebug.client_port=9003 script.php（混用也行）
• 注意：环境变量优先级高于 php.ini，但不会覆盖 zend_extension 这类加载项

常见失败原因：端口监听没开或被占

即使参数全对，VS Code 或 PhpStorm 没在监听 9003 端口，Xdebug 就会静默超时放弃。检查点包括：

• IDE 是否已点击 “Start Listening for Xdebug”（不是仅打开 launch.json）
• 终端执行 lsof -i :9003（macOS/Linux）或 netstat -ano | findstr :9003（Windows）确认端口占用情况
• 防火墙或杀毒软件是否拦截了本地回环连接
• PHP CLI 加载的 php.ini 路径是否正确——运行 php --ini 确认，别和 Web 版本搞混

Xdebug 3 的 CLI 调试不是“设个参数就自动连上”，它严格遵循“mode + start policy + client reachable”三要素。漏掉任意一个，日志里可能只有一句 Connection to client failed，连错误提示都不给你。