Xdebug 3 CLI调试必须显式触发，关键配置是xdebug.start_with_request=trigger；需通过环境变量XDEBUG_SESSION=1或php -dxdebug.start_with_request=1运行脚本，且xdebug.client_host须设为宿主机真实IP而非localhost。
CLI调试必须显式触发，xdebug.start_with_request=trigger 是关键
PHP命令行脚本（如定时任务）不会自动带 XDEBUG_SESSION_START 参数，Xdebug 3.x 默认不监听 CLI 请求。如果只配了 xdebug.mode=debug 但没设触发方式，断点永远不生效。
必须在 php.ini 中明确启用触发机制：
-
xdebug.start_with_request=trigger—— 这是唯一可靠的方式，支持通过环境变量或 GET/POST 参数激活 - 配合 CLI 使用：运行时加
XDEBUG_SESSION=1 php your_script.php，或直接php -dxdebug.start_with_request=1 your_script.php - 避免用
xdebug.start_with_request=yes：它会让所有 CLI 脚本无条件进入调试，干扰 cron 日志和自动化流程
PhpStorm 的 CLI Debug 配置不能复用 Web Server 设置
Web 页面调试走的是 HTTP 请求链路，而 CLI 调试是进程直连，路径映射、服务器配置、IDE Key 传递方式完全不同。直接套用 Web 配置会提示 “No path mapping found” 或连接超时。
正确做法是单独建一个 PHP Script 类型的 Run Configuration：
立即学习“PHP免费学习笔记（深入）”；
- Script path 指向你的定时脚本（如
app/console schedule:run） - 确保 PHP interpreter 选对版本（和 cron 实际调用的一致，别用 WSL 路径混 Windows）
- Environment variables 里手动加
XDEBUG_SESSION=PHPSTORM（值要和php.ini中xdebug.idekey一致） - 不要勾选 “Use path mappings”，除非你用 Docker 或远程挂载——本地 CLI 调试通常不需要
xdebug.client_host 在 CLI 场景下必须填宿主机 IP，不是 localhost
Windows + WSL、Docker Desktop、或某些虚拟化环境里，CLI 进程实际运行在子系统中，localhost 指向的是容器/WSL 自身回环，而非 PhpStorm 所在的 Windows 主机。结果就是 PhpStorm 监听端口收不到连接。
查清 PhpStorm 所在系统的实际 IP（非 127.0.0.1）：
- Windows：执行
ipconfig | findstr "IPv4"，取非虚拟网卡的 IPv4 地址（如192.168.1.105） - macOS：执行
ifconfig | grep "inet " | grep -v 127.0.0.1 - 把这个 IP 填进
php.ini：xdebug.client_host=192.168.1.105 - 同时确认 PhpStorm 的
Debug → Xdebug → Debug port和php.ini的xdebug.client_port完全一致（默认 9003）
定时任务调试失败时，优先检查 php --ini 加载的是哪个 php.ini
cron 或 systemd 启动的 PHP 进程，往往不读你改过的 Apache/Nginx 下的 php.ini，而是加载 CLI 专属配置，路径常为 /etc/php/*/cli/php.ini（Linux）或 phpstudy_pro\Extensions\php\php7.4.3nts\php.ini（Windows phpstudy）。
验证方法：
- 在定时脚本开头加
var_dump(php_ini_loaded_file()); die();，运行看输出路径 - 或直接在终端执行
php --ini，确认 “Loaded Configuration File” 行指向的文件 - 务必在这个文件里写入 Xdebug 配置，而不是你以为的那个
php.ini - 修改后不用重启 Apache，但需确保 cron 调用的是同一 PHP 二进制：用
which php或php -v核对版本和路径
CLI 调试最易被忽略的点：Xdebug 配置分散在多个 php.ini 文件中，且 xdebug.client_host 在容器/WSL 环境下必须是真实局域网 IP，填 localhost 就是白配。
