VSCode运行PHP CLI脚本时Xdebug无法命中断点求助

按以下步骤逐一排查调整：

• 第一步：确认CLI模式加载的配置文件路径
  终端执行php --ini，核对输出中Loaded Configuration File对应的路径，确保你修改的php.ini是CLI实际加载的文件。不少环境下PHP会为CLI、FPM分别提供独立的php.ini配置，改到FPM配置文件的话CLI场景不会生效。
• 第二步：修正php.ini内的Xdebug配置
  删掉无用的xdebug.discover_client_host = 1配置，该配置仅对web请求调试生效，CLI场景下会干扰客户端地址识别；同时显式指定客户端地址和端口，避免localhost解析到IPv6地址导致连接失败，最终配置如下：

  zend_extension=/usr/local/lib/php/pecl/20210902/xdebug.so
  xdebug.mode = debug
  xdebug.start_with_request = yes
  xdebug.client_host = 127.0.0.1
  xdebug.client_port = 9003
  

  改完执行php -v，确认输出中包含Xdebug版本信息，证明扩展加载正常无报错。
• 第三步：修正调试操作顺序与launch.json配置
  直接在终端执行脚本命不中断点的核心原因是启动顺序错误：
  1. 打开VSCode「运行和调试」面板，选择Listen for Xdebug配置，点击启动按钮，待底部状态栏出现橙色调试状态条，证明VSCode已经在9003端口正常监听
  2. 回到终端执行php myscript.php，即可正常命中提前打好的断点
     如果你想使用「直接启动当前打开脚本」的调试模式，把launch.json中对应配置项修改为如下内容，解决原配置随机端口和php.ini固定端口不匹配的问题：

  {
      "name": "Launch currently open script",
      "type": "php",
      "request": "launch",
      "program": "${file}",
      "cwd": "${fileDirname}",
      "port": 9003
  }
  

• 第四步：端口占用排查
  如果调整完仍提示连接失败，执行lsof -i :9003查看9003端口是否被其他程序占用，若存在占用，要么关闭占用进程，要么将xdebug.client_port和launch.json中的监听端口同步修改为同一个未被占用的端口即可。

注意：如果你是在Docker、WSL2等虚拟/容器环境中运行PHP脚本，xdebug.client_host不能设置为127.0.0.1，需要替换为宿主机的实际可达IP地址。

内容的提问来源于stack exchange，提问作者Sam Germain