Laravel Sail 10+RoadRunner配置Xdebug断点无效求助

一、修正Sail环境变量配置 #

在项目根目录的.env文件中，配置Xdebug相关参数：

SAIL_XDEBUG_MODE=debug,develop
SAIL_XDEBUG_CONFIG="client_host=host.docker.internal client_port=9003 start_with_request=yes idekey=PHPSTORM"

• client_host=host.docker.internal：适配M1 Mac容器访问宿主机的正确地址，避免用localhost或127.0.0.1（容器内指向自身）
• start_with_request=yes：强制Xdebug在进程启动时连接调试器，适配RoadRunner常驻worker的特性
• client_port=9003：对应Xdebug 3的默认调试端口（PHP8.2搭配的是Xdebug3，若用Xdebug2则改为9000）

二、PhpStorm核心调试配置 #

1. 开启调试监听
   点击PhpStorm右上角的电话图标（Start Listening for PHP Debug Connections），确保图标处于高亮状态。

2. 配置服务器路径映射

• 打开Settings > Languages & Frameworks > PHP > Servers
• 添加新服务器：
  • 名称：自定义（如Laravel Sail）
  • 主机：localhost（或本地访问项目的域名）
  • 端口：80（或Sail映射的自定义端口）
  • 勾选Use path mappings，将本地项目根目录映射到容器内的/var/www/html

3. CLI解释器绑定容器

• 打开Settings > Languages & Frameworks > PHP
• 点击CLI解释器右侧的...，选择From Docker, Vagrant, etc.，再选Docker Compose
• 服务选择laravel.test（Sail默认服务名），确认PHP版本为8.2且Xdebug已启用

三、适配RoadRunner Worker配置 #

RoadRunner的worker是常驻进程，需确保Xdebug在worker启动时初始化，修改项目根目录的.rr.yaml：

rpc:
  listen: tcp://127.0.0.1:6001

server:
  command: "php artisan roadrunner:worker"
  env:
    - XDEBUG_MODE=debug,develop
    - XDEBUG_CONFIG=client_host=host.docker.internal client_port=9003 start_with_request=yes idekey=PHPSTORM

http:
  address: 0.0.0.0:8080
  middleware: ["static", "gzip"]
  static:
    dir: "public"
    forbid: [".php", ".htaccess"]

在server.env中重复Xdebug配置，确保worker进程继承正确的调试环境变量。

四、验证与重启操作 #

1. 重启Sail容器：

sail down -v
sail up -d

2. 验证Xdebug加载状态：
   进入容器执行命令，确认Xdebug已加载：

sail exec laravel.test php -v

输出应包含with Xdebug v3.x.x的字样。

3. 断点测试：
   在控制器、路由或业务代码中设置断点，通过浏览器访问对应页面/接口，或执行sail artisan test等命令，检查PhpStorm是否捕获到调试会话。

五、处理PhpStorm多标签问题 #

sail up时生成的Artisan和roadrunner-worker标签，是因为Xdebug自动连接了启动时的常驻进程。可通过以下方式调整：

• 打开Settings > Build, Execution, Deployment > Debugger > Data Views > Auto-opening
• 仅保留Show debug window on breakpoint的勾选，或在调试会话列表中右键不需要的进程，选择Stop或Remove from list

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