VSCode调试Docker容器中PHP服务失败：错误代码3（缺少选项）

问题概况 #

已经查过StackOverflow上的相关问题，但都没解决。核心问题是程序没法在断点处停下来，查看Xdebug日志发现feature_set -i 5这一行报错：invalid or missing options（错误代码3）。

环境信息 #

• 操作系统：Ubuntu 22.04
• IDE：VS Code 1.85.1
• 运行环境：Docker容器（PHP 8.0 + Apache），已安装mysqli、Xdebug扩展

测试代码（第2行设置断点） #

<?php
echo xdebug_info();
#phpinfo()

相关配置文件 #

VS Code调试配置（launch.json） #

"version": "0.2.0",
"configurations": [
  {
    "name": "Listen for Xdebug",
    "type": "php",
    "request": "launch",
    "port": 9003,
    "hostname": "localhost",
    "log": true,
    "externalConsole": false,
    "pathMappings": {
      "/var/www/html": "${workspaceFolder}"
    },
    "xdebugSettings": {
      "idekey": "VSCODE"
    }
  }
]

容器内Xdebug配置（xdebug.ini） #

[xdebug]
#zend-extension=/usr/local/lib/php/extensions/no-debug-non-zts-20200930/xdebug.so
xdebug.default_enable=1
xdebug.remote_enable=1
xdebug.remote_port=9003
xdebug.remote_handler=dbgp
xdebug.remote_connect_back=0
xdebug.client_host=host.docker.internal
xdebug.log=/tmp/xdebug.log
xdebug.idekey=VSCODE
xdebug.remote_autostart=1
xdebug.discover_client_host=0
xdebug.start_with_request=yes 
xdebug.mode=debug
xdebug.remote_connect_back=1

解决步骤 #

1. 清理Xdebug配置中的冲突项 #

Xdebug 3.x已经改用新参数，旧的remote_*参数会和新参数冲突，直接保留3.x的标准配置：
修改后的xdebug.ini：

[xdebug]
zend-extension=/usr/local/lib/php/extensions/no-debug-non-zts-20200930/xdebug.so
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=host.docker.internal
xdebug.client_port=9003
xdebug.log=/tmp/xdebug.log
xdebug.idekey=VSCODE

• 取消zend-extension的注释，确保Xdebug能正常加载（如果容器已经自动加载可保留注释，但显式声明更稳妥）
• 删掉所有remote_*开头的旧版参数，改用Xdebug 3的client_*参数
• 保留start_with_request=yes，确保请求启动时自动触发调试

2. 修正VS Code的调试配置 #

移除xdebugSettings里的idekey（Xdebug 3会自动识别，这个配置可能就是导致feature_set报错的原因），同时把hostname改成0.0.0.0，确保能接收来自容器的连接：
修改后的launch.json：

"version": "0.2.0",
"configurations": [
  {
    "name": "Listen for Xdebug",
    "type": "php",
    "request": "launch",
    "port": 9003,
    "hostname": "0.0.0.0",
    "log": true,
    "externalConsole": false,
    "pathMappings": {
      "/var/www/html": "${workspaceFolder}"
    }
  }
]

3. 验证配置生效 #

• 重启Docker容器，让Xdebug的新配置生效
• 在VS Code里启动「Listen for Xdebug」调试会话
• 访问测试页面，查看Xdebug日志是否有成功连接的记录，同时检查断点是否正常触发

4. 额外排查点 #

• 确认宿主机的9003端口没被其他程序占用
• 在容器内执行ping host.docker.internal，确保能正常解析并连通宿主机

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