Docker+XDebug+VSCode环境下PHPUnit断点无法触发求助

核心排查步骤 #

1. 区分CLI与Apache的PHP环境配置 #

浏览器请求用的是Apache的PHP环境，但PHPUnit依赖CLI版PHP，两者的配置文件通常是分开的：

• 进入容器执行 php -v，确认输出中包含XDebug版本，没有则说明CLI环境未加载XDebug
• 执行 php --ini 查看CLI加载的INI文件路径，检查其中XDebug配置：
  • 必须开启 xdebug.mode=debug（或包含debug的组合值，比如develop,debug）
  • xdebug.client_host 不能填localhost，Docker容器内的localhost指向自身，需改为host.docker.internal（Windows/macOS）或宿主机局域网IP（Linux）
  • 确认 xdebug.client_port=9015 与VSCode配置一致
  • 若设置 xdebug.start_with_request=trigger，则需额外传递XDEBUG_TRIGGER=1环境变量

2. 验证PHPUnit的执行触发逻辑 #

• 直接在容器内执行测试时，需带上XDebug触发参数：XDEBUG_TRIGGER=1 phpunit
• 检查phpunit.xml的配置，确保已添加XDebug相关环境变量：

  <php>
      <env name="XDEBUG_MODE" value="debug"/>
      <env name="XDEBUG_TRIGGER" value="1"/>
  </php>
  

3. 修正VSCode调试配置 #

确保launch.json针对CLI调试的配置正确，重点是路径映射：

{
    "name": "Listen for XDebug (CLI)",
    "type": "php",
    "request": "launch",
    "port": 9015,
    "pathMappings": {
        "/var/www/html": "${workspaceFolder}" // 必须与容器内代码根目录完全对应
    },
    "log": true // 开启日志方便排查连接失败原因
}

4. 确认断点有效性 #

• 断点需设在可执行代码行，避免空行、注释行或未被执行的分支
• 测试方法内可临时添加dump('test running')，确认该测试确实在运行
• 检查setUp/tearDown等生命周期方法的断点，需确保测试类会执行这些方法

5. 排查网络连通性 #

• 在容器内ping宿主机IP（host.docker.internal或局域网IP），确认网络可达
• 检查宿主机9015端口是否被占用：Windows执行netstat -ano | findstr :9015，Linux/macOS执行lsof -i :9015

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