Windows环境下Laravel Sail Docker配置Xdebug并连接PhpStorm

我刚在Windows上搞定了这套配置，给你一步步拆解操作：

1. 修改Dockerfile安装Xdebug #

打开项目内的vendor/laravel/sail/runtimes/8.0/Dockerfile，找到安装PHP扩展的代码块，把php8.0-xdebug添加到扩展列表里：

&& apt-get install -y php8.0-cli php8.0-dev \
   php8.0-pgsql php8.0-sqlite3 php8.0-gd \
   php8.0-curl php8.0-memcached \
   php8.0-imap php8.0-mysql php8.0-mbstring \
   php8.0-xml php8.0-zip php8.0-bcmath php8.0-soap \
   php8.0-intl php8.0-readline \
   php8.0-msgpack php8.0-igbinary php8.0-ldap \
   php8.0-redis php8.0-xdebug \  # 新增这行

修改完成后，在项目根目录运行命令重新构建镜像：

sail build laravel.test

2. 配置docker-compose.yml的Xdebug环境变量 #

打开项目根目录的docker-compose.yml，找到laravel.test服务的environment节点，添加Xdebug相关配置：

environment:
    WWWUSER: '${WWWUSER}'
    LARAVEL_SAIL: 1
    PHP_IDE_CONFIG: 'serverName=localhost'
    XDEBUG_MODE: debug
    XDEBUG_CONFIG: 'client_host=host.docker.internal client_port=9003 start_with_request=yes'

• client_host=host.docker.internal：Windows环境下，Docker容器通过这个地址可以访问主机
• client_port=9003：Xdebug 3的默认端口，如果你PhpStorm用的是9000可以改成对应值，建议用9003避免冲突

配置好后重启容器：

sail down && sail up -d

3. PhpStorm调试配置 #

3.1 设置CLI解释器 #

1. 按Ctrl+Alt+S打开PhpStorm设置面板
2. 搜索「PHP」→「CLI Interpreter」
3. 点击右上角的+，选择「Docker」
4. 在弹窗里选择镜像sail-8.0/app，点击「OK」等待加载完成，最后应用设置

3.2 配置服务器映射 #

1. 还是在设置面板，找到「PHP」→「Servers」
2. 点击+新增服务器：
   • Name：填localhost（必须和PHP_IDE_CONFIG里的serverName一致）
   • Host：localhost
   • Port：80（或者你.env里设置的APP_PORT值）
   • Debugger：选择Xdebug
   • 勾选「Use path mappings」，把本地项目根目录映射到容器内的/var/www/html
3. 保存应用设置

3.3 开启Xdebug监听 #

点击PhpStorm右上角的「电话」图标（快捷键Ctrl+Shift+F9），确保图标变成绿色，表示正在监听调试请求

4. 测试调试效果 #

1. 在代码里设置断点，比如在routes/web.php的首页路由里：

   Route::get('/', function () {
       $debugTest = "Hello Xdebug!"; // 点击行号左侧设置断点
       return view('welcome');
   });
   

2. 访问http://localhost，PhpStorm会自动弹出调试窗口，你可以查看变量、单步执行代码了

如果遇到调试没触发的情况，先检查这几点：

• 运行sail exec laravel.test php -v，确认输出里有Xdebug版本信息
• 检查PhpStorm的Xdebug端口（设置里搜「Xdebug」）和XDEBUG_CONFIG里的端口是否一致
• 确认Windows防火墙没有拦截PhpStorm的9003端口请求

内容的提问来源于stack exchange，提问作者Ruud van de Ven