Laravel Sail SAIL_XDEBUG_MODE配置无效 无法调试Web请求问题

你遇到的CLI和Web端Xdebug配置不一致的问题，根源是两个原因：

1. PHP CLI和PHP-FPM默认使用独立的配置目录，你当前的Dockerfile只把自定义配置写入了CLI的配置目录，没有同步到FPM的配置目录
2. PHP-FPM进程启动时默认会过滤掉系统环境变量，你在docker-compose.yml中设置的XDEBUG_MODE等环境变量只能被CLI进程读取，FPM进程无法获取，因此Web端只能读取ini文件中的固定配置

步骤1：修改.env配置 #

在项目根目录的.env文件中添加以下配置：

SAIL_XDEBUG_MODE=debug,develop
SAIL_XDEBUG_CONFIG=client_host=host.docker.internal client_port=9003

步骤2：发布Sail自定义配置 #

执行以下命令发布Sail的runtime配置到项目本地，避免直接修改vendor目录下的文件：

sail artisan sail:publish

执行完成后项目根目录会生成docker目录，包含对应PHP版本的配置文件。

步骤3：修改Dockerfile同步配置到FPM #

编辑docker/8.0/Dockerfile，找到以下行：

COPY php.ini /etc/php/8.0/cli/conf.d/99-sail.ini

在下方新增一行，把配置同步到FPM的配置目录：

COPY php.ini /etc/php/8.0/fpm/conf.d/99-sail.ini

步骤4：配置Supervisor让FPM读取环境变量 #

编辑docker/8.0/supervisord.conf，找到[program:php-fpm]配置块，在块内新增一行环境变量配置：

environment=XDEBUG_MODE=%(ENV_XDEBUG_MODE)s,XDEBUG_CONFIG=%(ENV_XDEBUG_CONFIG)s

步骤5：重新构建并重启容器 #

执行以下命令重新构建Sail镜像并重启容器：

sail build --no-cache
sail up -d

步骤6：验证PhpStorm配置 #

1. 进入PhpStorm设置 -> PHP -> 服务器，新增服务器：
   • 名称填写my.local（和docker-compose.yml中PHP_IDE_CONFIG的serverName保持一致）
   • 主机填写你的项目访问域名（比如localhost），端口80，调试器选择Xdebug
   • 勾选「使用路径映射」，将本地项目根目录映射到容器内的/var/www/html
2. 开启PhpStorm的Xdebug监听（右上角电话形状的图标，点亮即可）

配置完成后CLI和Web端的Xdebug配置就会保持一致，均可正常触发断点调试。

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