如何在远程Docker容器中配置PhpStorm的Xdebug远程调试

一、确认Xdebug核心配置（适配Xdebug 3.x） #

先确保容器内的Xdebug配置文件（通常为/usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini）包含以下关键参数，替换为你的实际信息：

xdebug.mode = debug
xdebug.start_with_request = yes
# 填写远程服务器能访问到的本地IP（局域网IP/公网IP）
xdebug.client_host = 192.168.1.100
xdebug.client_port = 9003
xdebug.log = /var/log/xdebug.log
xdebug.idekey = PHPSTORM

注意：Xdebug 3.x与2.x参数差异极大，请勿混用旧配置。client_host必须是容器能主动访问到的本地IP——因为Xdebug是容器向本地PhpStorm发起连接，而非本地反向连接容器。

二、Docker环境配置检查 #

1. Dockerfile确保Xdebug安装正确 #

你的Dockerfile需包含Xdebug的安装与配置步骤，示例如下：

# 安装Xdebug（以PHP 8.x为例）
RUN pecl install xdebug && docker-php-ext-enable xdebug
# 复制本地Xdebug配置文件到容器指定路径
COPY ./docker/php/xdebug.ini /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini

2. docker-compose.yml配置优化 #

无需将9003端口映射到远程服务器（因连接方向为容器→本地），但需确保容器网络能访问本地IP：

services:
  php:
    build: ./docker/php
    volumes:
      # 映射本地项目代码到容器内，路径需与后续PhpStorm配置对应
      - ./:/var/www/html
    environment:
      # 可选：通过环境变量快速切换调试模式
      - XDEBUG_MODE=debug
      - XDEBUG_CLIENT_HOST=192.168.1.100

三、PhpStorm关键配置 #

1. 配置远程PHP解释器 #

• 打开PhpStorm → File → Settings → PHP → CLI Interpreter
• 点击+ → 选择From Docker, Vagrant, VM, WSL, Remote...
• 选择Docker Compose，指定远程服务器的docker-compose.yml路径，选中对应PHP服务，等待PhpStorm自动识别容器内的PHP可执行文件（如/usr/local/bin/php）
• 确认解释器配置生效，可查看Xdebug版本信息

2. 配置Xdebug调试参数 #

• 进入Settings → PHP → Debug → Xdebug
• 确保Debug port设置为9003（与xdebug.client_port保持一致）
• 勾选Can accept external connections

3. 配置路径映射 #

• 进入Settings → PHP → Servers
• 点击+添加服务器：
  • Name自定义（需与xdebug.idekey对应，或保持默认）
  • Host填写项目访问的域名/远程服务器IP
  • Port填写项目运行端口（如80）
  • 勾选Use path mappings，将本地项目根目录映射到容器内的项目根目录（例如本地/Users/xxx/project → 容器/var/www/html）

四、网络连通性验证 #

1. 在远程服务器上ping本地IP，确认网络可达
2. 本地防火墙开放9003端口（Windows：防火墙高级设置添加入站规则；Mac：系统设置→网络→防火墙→允许PhpStorm通信）
3. 在容器内测试本地9003端口连通性：执行telnet 192.168.1.100 9003，能连通则网络正常

五、调试验证 #

1. 点击PhpStorm右上角的电话图标，开启调试监听
2. 在代码中设置断点
3. 访问远程项目页面或执行CLI命令，检查断点是否触发
4. 若未触发，查看容器内/var/log/xdebug.log，日志会明确标注连接失败原因（如无法解析IP、端口不通等）

内容的提问来源于stack exchange，提问作者Alexis C.