Laravel Sail环境下PhpStorm仅调试server.php问题求助

通过Sail安装最新版Laravel（执行命令：curl -s "https://laravel.build/example-app" | bash），并在.env中添加配置：SAIL_XDEBUG_MODE=develop,debug,profile。

遇到以下调试问题：

• 开启PhpStorm「在PHP脚本首行断点」设置时，调试仅停在server.php文件，生成的cachegrind.out.21也仅包含该文件信息。
• 关闭「首行断点」后，在public/index.php添加断点无响应，但VSCode中相同操作可正常触发。
• 删除PhpStorm服务器配置后刷新浏览器，会弹出「Xdebug传入连接」窗口，显示服务器文件路径为/var/www/html/vendor/laravel/framework/src/Illuminate/Foundation/resources/server.php，确认后配置与之前一致。

已配置PhpStorm服务器：添加主机localhost:80，本地项目文件映射到容器内/var/www/html目录。

Xdebug日志内容如下：

[26] Log opened at 2023-06-05 10:03:18.607155
[26] [Config] INFO: Trigger value for 'XDEBUG_TRIGGER' not found, falling back to 'XDEBUG_SESSION'
[26] [Config] INFO: No shared secret: Activating
[26] [Step Debug] INFO: Connecting to configured address/port: host.docker.internal:9003.
[26] [Step Debug] INFO: Connected to debugging client: host.docker.internal:9003 (through xdebug.client_host/xdebug.client_port).
[26] [Step Debug] -> <init xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug" fileuri="file:///var/www/html/vendor/laravel/framework/src/Illuminate/Foundation/resources/server.php" language="PHP" xdebug:language_version="8.2.6" protocol_version="1.0" appid="26" idekey="XDEBUG_ECLIPSE"><engine version="3.2.0"><![CDATA[Xdebug]]></engine><author><![CDATA[Derick Rethans]]></author><url><![CDATA[https://xdebug.org]]></url><copyright><![CDATA[Copyright (c) 2002-2022 by Derick Rethans]]></copyright></init>

[26] [Step Debug] <- feature_set -i 1 -n show_hidden -v 1
[26] [Step Debug] -> <response xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug" command="feature_set" transaction_id="1" feature="show_hidden" success="1"></response>

[26] [Step Debug] <- feature_set -i 2 -n max_depth -v 1
[26] [Step Debug] -> <response xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug" command="feature_set" transaction_id="2" feature="max_depth" success="1"></response>

[26] [Step Debug] <- feature_set -i 3 -n max_children -v 100
[26] [Step Debug] -> <response xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug" command="feature_set" transaction_id="3" feature="max_children" success="1"></response>

[26] [Step Debug] <- feature_set -i 4 -n extended_properties -v 1
[26] [Step Debug] -> <response xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug" command="feature_set" transaction_id="4" feature="extended_properties" success="1"></response>

[26] [Step Debug] <- feature_set -i 5 -n notify_ok -v 1
[26] [Step Debug] -> <response xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug" command="feature_set" transaction_id="5" feature="notify_ok" success="1"></response>

[26] [Step Debug] <- feature_set -i 6 -n resolved_breakpoints -v 1
[26] [Step Debug] -> <response xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug" command="feature_set" transaction_id="6" feature="resolved_breakpoints" success="1"></response>

[26] [Step Debug] <- feature_set -i 7 -n breakpoint_include_return_value -v 1
[26] [Step Debug] -> <response xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug" command="feature_set" transaction_id="7" feature="breakpoint_include_return_value" success="1"></response>

[26] [Step Debug] <- stdout -i 8 -c 1
[26] [Step Debug] -> <response xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug" command="stdout" transaction_id="8" success="1"></response>

[26] [Step Debug] <- status -i 9
[26] [Step Debug] -> <response xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug" command="status" transaction_id="9" status="starting" reason="ok"></response>

[26] [Step Debug] <- step_into -i 10
[26] [Step Debug] -> <response xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug" command="step_into" transaction_id="10" status="break" reason="ok"><xdebug:message filename="file:///var/www/html/vendor/laravel/framework/src/Illuminate/Foundation/resources/server.php" lineno="3"></xdebug:message></response>

[26] [Step Debug] <- eval -i 11 -- aXNzZXQoJF9TRVJWRVJbJ1BIUF9JREVfQ09ORklHJ10p
[26] [Step Debug] -> <response xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug" command="eval" transaction_id="11"><property type="bool"><![CDATA[0]]></property></response>

[26] [Step Debug] <- eval -i 12 -- aXNzZXQoJF9TRVJWRVJbJ1NFUlZFUl9OQU1FJ10p
[26] [Step Debug] -> <response xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug" command="eval" transaction_id="12"><property type="bool"><![CDATA[1]]></property></response>

[26] [Step Debug] <- eval -i 13 -- KHN0cmluZykoJF9TRVJWRVJbJ1NFUlZFUl9OQU1FJ10p
[26] [Step Debug] -> <response xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug" command="eval" transaction_id="13"><property type="string" size="7" encoding="base64"><![CDATA[MC4wLjAuMA==]]></property></response>

[26] [Step Debug] <- eval -i 14 -- KHN0cmluZykoJF9TRVJWRVJbJ1NFUlZFUl9QT1JUJ10p
[26] [Step Debug] -> <response xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug" command="eval" transaction_id="14"><property type="string" size="2" encoding="base64"><![CDATA[ODA=]]></property></response>

[26] [Step Debug] <- eval -i 15 -- KHN0cmluZykoJF9TRVJWRVJbJ1JFUVVFU1RfVVJJJ10p
[26] [Step Debug] -> <response xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug" command="eval" transaction_id="15"><property type="string" size="12" encoding="base64"><![CDATA[L2Zhdmljb24uaWNv]]></property></response>

[26] [Step Debug] <- stack_get -i 16
[26] [Step Debug] -> <response xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug" command="stack_get" transaction_id="16"><stack where="{main}" level="0" type="file" filename="file:///var/www/html/vendor/laravel/framework/src/Illuminate/Foundation/resources/server.php" lineno="3"></stack></response>

[26] [Step Debug] <- run -i 17
[26] [Step Debug] -> <response xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug" command="run" transaction_id="17" status="stopping" reason="ok"></response>

[26] [Step Debug] <- detach -i 18
[26] [Step Debug] -> <response xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug" command="detach" transaction_id="18" status="stopping" reason="ok"></response>

[26] Log closed at 2023-06-05 10:03:18.701446

针对Laravel Sail + PhpStorm的Xdebug调试问题，按以下步骤配置：

1. 完善Xdebug环境配置 #

在.env中补充Xdebug的客户端连接配置，确保会话能正确识别PhpStorm：

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

添加完成后重启Sail容器：

./vendor/bin/sail down && ./vendor/bin/sail up -d

2. 修正PhpStorm服务器映射 #

• 打开PhpStorm的「Settings/Preferences」→「Languages & Frameworks」→「PHP」→「Servers」
• 确保服务器配置的**「Use path mappings」**已勾选
• 映射规则设置为：本地项目根目录 → 容器内/var/www/html，无需单独添加子目录映射（子目录会自动继承根目录规则）
• 取消勾选「Force break at first line in PHP scripts」（即「首行断点」设置）

3. 开启PhpStorm调试监听 #

• 点击PhpStorm右上角的电话图标，启动「Start Listening for PHP Debug Connections」
• 安装浏览器Xdebug扩展（如Xdebug Helper），设置IDE Key为PHPSTORM，访问项目时开启调试模式

4. 验证并修复断点触发问题 #

• 在业务代码（如app/Http/Controllers/WelcomeController.php）中添加断点
• 开启浏览器调试模式后访问对应路由，检查PhpStorm是否触发断点
• 若仍无响应，执行以下操作：
  • 清除Laravel缓存：./vendor/bin/sail artisan cache:clear && ./vendor/bin/sail artisan config:clear
  • 重启PhpStorm和Sail容器

5. 排查路径映射一致性 #

从Xdebug日志来看，调试会话已成功连接但仅停在server.php，核心问题大概率是路径映射不匹配：

• 检查PhpStorm服务器配置中的「Absolute path on the server」是否完全等于容器内路径/var/www/html，避免拼写错误或多余后缀
• 右键点击本地项目根目录，选择「Deployment」→「Download from...」，同步本地与容器内文件，避免因文件不一致导致断点失效

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