求助：Docker环境下PhpStorm中Xdebug无法在断点处停止

问题描述 #

在WSL、Docker和Laravel Sail环境运行Laravel项目时，Xdebug可在代码第一行中断，但无法停留在手动设置的自定义断点处，怀疑路径映射存在问题，尝试多种配置方案后仍未解决。

环境配置 #

环境变量：

FORWARD_DB_PORT=33064
APP_PORT=8014
SAIL_XDEBUG_MODE=develop,debug

PhpStorm相关设置截图：

• Xdebug配置
• 路径映射

已尝试的配置参考：

• JetBrains官方Xdebug配置文档
• Laravel Sail与Xdebug、PhpStorm调试整合教程
• PhpStorm远程Xdebug路径映射配置方案

排查与解决步骤 #

1. 严格校验路径映射一致性 #

从截图路径映射来看，需确保：

• 本地路径使用WSL内的绝对路径（例如/home/xxx/laravel-project），而非Windows挂载路径（\\wsl$\...）
• 容器路径必须与Laravel Sail默认的项目根路径/var/www/html完全一致，不能有拼写错误
• 确认已勾选Use path mappings，且映射条目是整个项目根目录的映射，而非单个文件或子目录

2. 验证容器内Xdebug核心配置 #

进入Sail容器执行以下命令检查Xdebug参数：

sail exec php php -i | grep xdebug

重点确认：

• xdebug.client_host：WSL环境下需设置为host.docker.internal，确保容器能访问宿主机的PhpStorm调试端口
• xdebug.client_port：必须与PhpStorm中设置的端口一致（Xdebug 3默认是9003，Xdebug 2为9000）
• xdebug.idekey：需匹配PhpStorm的调试IDE Key（默认值为PHPSTORM）

3. 确认断点有效性 #

• 断点需打在可执行代码行上，避免注释、空行、类/方法定义等非执行行
• 暂时关闭PhpStorm的Force break at first line in PHP scripts选项，排除首行中断对自定义断点的干扰
• 清理所有旧断点，重新设置新断点测试

4. 检查WSL与Docker的端口连通性 #

• 在WSL终端执行netstat -tulpn | grep 9003（替换为你的Xdebug端口），确认端口未被占用
• 确保Docker容器的Xdebug端口已正确转发到WSL主机，Laravel Sail默认会自动处理，但可通过docker ps查看容器端口映射确认

内容的提问来源于stack exchange，提问作者Mr-Faizan