Xdebug 3 调试必须显式触发，不依赖全局监听；浏览器通过 URL 参数 ?XDEBUG_TRIGGER=1 或 Cookie 激活，CLI 则需设置 XDEBUG_MODE=debug 环境变量，且 xdebug.mode=debug 与 xdebug.start_with_request=trigger 必须协同配置才生效。
Xdebug 3 的调试触发机制和 Xdebug 2 完全不同，不再依赖 xdebug.remote_autostart 或全局监听。必须明确指定“谁来触发”“何时触发”，否则断点永远不生效。
浏览器访问时怎么触发调试
浏览器本身不主动“发起调试”，Xdebug 3 需要显式信号才能启动会话。最常用的是通过 URL 参数或 Cookie：
-
XDEBUG_TRIGGER是默认启用的触发键，直接在 URL 后加?XDEBUG_TRIGGER=1即可（如http://localhost/index.php?XDEBUG_TRIGGER=1） - 也可用 Cookie 方式：浏览器访问前手动设置名为
XDEBUG_TRIGGER、值为任意非空字符串的 Cookie（VS Code 的 PHP Debug 插件点击“Start Listening”后会自动注入该 Cookie） - 注意：
xdebug.start_with_request=yes会让所有请求都进调试，开发环境慎用；default表示只响应触发信号，更安全 - 如果用了 Nginx + PHP-FPM，确保
fastcgi_param没过滤掉XDEBUG_TRIGGER类请求头或参数（某些安全配置会 strip 掉下划线开头的变量）
CLI 脚本调试必须靠环境变量
PHP 命令行模式没有 URL、没有 Cookie，XDEBUG_TRIGGER 参数无效。唯一可靠方式是通过环境变量启动：
- 执行脚本前设置：
XDEBUG_MODE=debug php script.php - 或在
launch.json的env字段中写："env": { "XDEBUG_MODE": "debug" }—— 但仅当配置了program字段时才生效（即“Launch Current Script”模式） -
xdebug.start_with_request=trigger在 CLI 下也有效，此时需额外传入XDEBUG_TRIGGER=1环境变量，和 Web 模式逻辑一致 - 常见错误：在终端里只运行
php script.php，却没配XDEBUG_MODE，Xdebug 根本不初始化调试通道
自动触发（start_with_request=yes）的风险点
这个配置看起来最省事，实际最容易引发问题：
- 它会让每个 HTTP 请求、每个 CLI 调用都尝试连接 IDE，一旦 IDE 没在监听，Xdebug 会阻塞几秒再超时，拖慢整个响应速度
- Docker 场景下尤其危险：容器内
xdebug.client_host若设成127.0.0.1，而 IDE 在宿主机，连接必然失败且无提示 - CI/CD 或定时任务中若误启用此配置，会导致日志刷屏、连接拒绝报错，甚至因超时引发任务失败
- 真正需要“无感调试”的场景极少，多数时候应坚持显式触发（
trigger），既可控又可追溯
最容易被忽略的一点：Xdebug 3 的触发行为完全由 xdebug.mode 和 xdebug.start_with_request 共同决定，缺一不可。只改一个，另一项会覆盖或禁用触发逻辑。调试连不上，先盯住这两个配置的组合是否合理，比查端口、看日志更快。
