如何在Docker中配置Xdebug并在PhpStorm开启开发者助手与追踪

一、Docker环境下Xdebug基础配置 #

• 找到PHP容器内的Xdebug配置文件（通常路径为/usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini），添加/修改以下配置：

xdebug.mode = debug,develop,trace
xdebug.client_host = host.docker.internal  # Windows/macOS直接用这个；Linux需替换成宿主机IP
xdebug.client_port = 9003  # Xdebug 3默认端口，Xdebug 2请改成9000
xdebug.idekey = PHPSTORM
xdebug.start_with_request = yes

• 重启PHP容器生效：
  docker restart <你的PHP容器名称>

二、PhpStorm基础调试配置 #

• 配置PHP解释器：
  打开File > Settings > Languages & Frameworks > PHP，点击解释器下拉框的...，添加Docker解释器，选择你的PHP容器，系统会自动加载PHP版本和Xdebug信息。
• 配置服务器映射：
  进入File > Settings > Languages & Frameworks > PHP > Servers，新增服务器：
  • 名称填PHPSTORM（必须和xdebug.idekey一致）
  • 主机填本地开发域名/IP（比如localhost）
  • 端口填Web服务端口（通常是80）
  • 勾选Use path mappings，把本地项目根目录映射到容器内的项目路径（比如本地/Users/xxx/my-project对应容器/var/www/html）
• 开启调试监听：
  点击PhpStorm右上角的电话图标，开启Start Listening for PHP Debug Connections。

三、开启Xdebug开发者助手与追踪功能 #

1. 开发者助手（Xdebug Helper）配置 #

• 浏览器安装Xdebug Helper插件（Chrome/Edge商店搜「Xdebug Helper」，Firefox搜「Xdebug Helper for Firefox」）
• 右键插件图标选择Options，设置IDE key为PHPSTORM，切换插件状态为Debug模式
• 访问项目页面时，插件会自动向Xdebug发送调试请求，触发PhpStorm断点调试

2. 追踪（Trace）功能配置 #

Docker端配置

在Xdebug配置文件中追加以下参数：

xdebug.trace_output_dir = /tmp/xdebug-traces  # 确保容器内该目录存在且可写
xdebug.trace_format = 0  # 0为文本格式，1为HTML格式，按需选择
xdebug.trace_options = 0  # 0覆盖旧文件，1追加内容

重启PHP容器生效。

PhpStorm端操作

• 查看已有追踪文件：通过Docker容器的文件浏览器进入/tmp/xdebug-traces，下载.xt后缀的追踪文件，直接拖入PhpStorm即可自动解析，展示函数调用栈、参数值、执行时间等细节。
• 调试时自动生成追踪：打开Run > Edit Configurations，选中你的PHP调试配置（比如PHP Web Page），切换到Advanced标签页，勾选Collect debug traces，调试过程中会自动生成追踪文件并在PhpStorm中打开。

附相关配置截图：

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