Docker环境下如何为Symfony CLI命令按需启动Xdebug？

调整全局Xdebug配置消除常驻性能开销 #

将原有PHP配置中xdebug.start_with_request=yes修改为xdebug.start_with_request=trigger，该模式下Xdebug不会对所有脚本执行默认激活调试钩子，日常运行时和未安装Xdebug的性能表现完全一致，不会产生额外损耗。
配套的全局固定配置项（写入容器内的xdebug.ini文件，不会带来运行时开销）：

• xdebug.mode=debug 确保调试能力处于可用状态，避免触发条件满足时无法启动调试
• xdebug.trigger_value=SYMFONY_CONSOLE_DEBUG 自定义专属触发标识，避免与Web端的调试触发逻辑互相干扰
• xdebug.client_host=对应宿主机在Docker网络中的网关IP 确保容器内Xdebug能正常连接到宿主机上的IDE，避免调试连接失败

控制台命令按需触发调试的操作 #

CLI环境没有Web请求的传参机制，Xdebug3支持通过环境变量传递触发标识，全程不需要修改全局配置：

• 日常执行无调试需求的命令时，直接使用常规命令格式即可，例如php bin/console cache:clear，整个过程Xdebug完全不介入运行逻辑
• 需要调试指定控制台命令时，在执行命令前临时注入触发环境变量即可：
  容器内直接执行的场景：XDEBUG_TRIGGER=SYMFONY_CONSOLE_DEBUG php bin/console 你的待调试命令
  宿主机通过docker exec执行的场景：docker exec -e XDEBUG_TRIGGER=SYMFONY_CONSOLE_DEBUG 你的Symfony容器名称 php bin/console 你的待调试命令

配套IDE配置说明 #

• 保持IDE的Xdebug监听端口为9003（Xdebug3默认端口，注意不要和旧版Xdebug2的9000端口混淆）
• 无需为控制台场景单独配置调试入口，只要IDE处于Xdebug监听状态，带触发变量的命令执行时会自动完成连接，命中断点

注意事项 #

• 不要将触发用的环境变量写入容器全局环境变量或bash配置文件，否则会变回所有控制台命令默认启动调试，失去按需触发的性能优化意义
• trigger模式下仅单次带触发标识的命令会激活Xdebug，性能损耗仅发生在主动发起调试的单次执行过程中，不会影响其他命令的运行速度

内容的提问来源于stack exchange，提问作者simon.ro