Mac M1升级Monterey后VSCode中Xdebug无法启动求助

问题核心定位 #

从提供的配置和输出来看，存在两处关键冲突：

• 端口不匹配：xdebug.ini配置了xdebug.client_port=9000，但实际生效的本地端口为55058，且调试时9003端口处于监听状态，说明Xdebug实际使用的端口与VSCode配置不一致。
• 环境变量覆盖配置：xdebug.mode的本地值由环境变量XDEBUG_MODE设置为debug,develop，覆盖了ini文件的配置项。

分步修复方案 #

1. 统一Xdebug端口配置 #

Xdebug 3默认端口为9003，建议统一使用该端口避免冲突：
修改/opt/homebrew/etc/php/8.1/conf.d/99-xdebug.ini内容为：

zend_extension=xdebug
xdebug.mode=debug,develop
xdebug.start_with_request=yes
xdebug.client_port=9003
xdebug.log=/tmp/xdebug.log
xdebug.client_host=127.0.0.1

修改后CLI环境下无需重启，下次运行PHP自动生效；若使用Web服务，需重启对应服务。

2. 更新VSCode的launch.json配置 #

确保VSCode监听端口与Xdebug配置一致：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Listen for Xdebug",
      "type": "php",
      "request": "launch",
      "port": 9003,
      "log": true
    },
    {
      "name": "Launch currently open script",
      "type": "php",
      "request": "launch",
      "program": "${file}",
      "cwd": "${fileDirname}",
      "port": 9003,
      "runtimeArgs": [
        "-dxdebug.start_with_request=yes"
      ],
      "env": {
        "XDEBUG_MODE": "debug,develop",
        "XDEBUG_CONFIG": "client_port=9003"
      }
    },
    {
      "name": "Launch Built-in web server",
      "type": "php",
      "request": "launch",
      "runtimeArgs": [
        "-dxdebug.mode=debug,develop",
        "-dxdebug.start_with_request=yes",
        "-S",
        "localhost:0"
      ],
      "program": "",
      "cwd": "${workspaceRoot}",
      "port": 9003,
      "serverReadyAction": {
        "pattern": "Development Server \\(http://localhost:([0-9]+)\\) started",
        "uriFormat": "http://localhost:%s",
        "action": "openExternally"
      }
    }
  ]
}

3. 清除冲突的环境变量 #

检查终端或系统环境变量是否存在覆盖配置的情况：

• 在终端执行：

  echo $XDEBUG_CONFIG
  echo $XDEBUG_MODE
  

• 如果有输出，找到对应的配置文件（如~/.zshrc、~/.bashrc或系统环境变量配置文件），删除相关的环境变量设置行，然后重启终端。

4. 验证配置有效性 #

执行以下命令确认配置生效：

php -r "xdebug_info();"

确认输出中xdebug.client_port的Local Value和Master Value均为9003，xdebug.mode为debug,develop。

启动VSCode的「Listen for Xdebug」，运行PHP脚本测试断点是否正常触发。

额外排查点 #

• 确保VSCode的PHP Debug扩展为最新版本，避免版本兼容问题。
• 查看/tmp/xdebug.log日志内容：若调试时无日志，说明Xdebug未触发连接；若存在连接失败日志，根据日志提示调整配置。

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