Ubuntu下非sudo运行Docker Compose时PhpStorm无法触发Xdebug断点

核心问题在于sudo与普通用户运行Docker Compose时，容器的网络环境、挂载文件权限存在差异，导致Xdebug无法反向连接到宿主机的PhpStorm。以下是具体排查思路和解决步骤：

一、先确认核心差异点 #

1. 检查Docker网络连通性（普通用户容器） #

进入普通用户启动的PHP容器，执行以下命令验证：

# 解析host.docker.internal是否正确
ping host.docker.internal -c 3
# 测试宿主机9003端口是否可达
nc -zv host.docker.internal 9003

对比sudo启动的容器执行结果，如果普通用户下无法解析或连接失败，说明网络权限或配置存在问题。

2. 对比Xdebug实际生效配置 #

分别在两种启动方式的PHP容器中执行：

php -i | grep -A 20 "xdebug"

重点查看xdebug.client_host、xdebug.discover_client_host、xdebug.mode这几个参数的实际值，确认普通用户下Xdebug配置是否正常加载。

3. 查看Xdebug日志（关键排查手段） #

修改xdebug.ini，添加日志配置：

xdebug.log=/tmp/xdebug.log
xdebug.log_level=7

普通用户启动容器并触发请求后，进入容器查看日志：

cat /tmp/xdebug.log

日志中会明确显示Xdebug尝试连接调试客户端的过程，比如是否出现Could not connect to debugging client等错误信息。

二、针对性解决方案 #

1. 确保普通用户拥有Docker完整权限 #

如果普通用户未加入docker组，会导致部分网络操作受限：

sudo usermod -aG docker $USER
# 重新登录终端生效

2. 修复挂载配置文件的权限问题 #

宿主机上的xdebug.ini如果权限过高（仅root可读），普通用户启动的容器无法加载：

# 调整文件权限为所有用户可读
chmod 644 ./php/conf.d/xdebug.ini
# 或者调整文件所属用户为当前普通用户
chown $USER:$USER ./php/conf.d/xdebug.ini

3. 替换host.docker.internal为宿主机实际IP #

部分环境下普通用户的Docker无法正确解析host.docker.internal，直接指定宿主机IP：

1. 在宿主机执行hostname -I获取本地IP（比如192.168.1.100）
2. 修改xdebug.ini：

xdebug.client_host=192.168.1.100
# 关闭自动发现，强制使用指定IP
xdebug.discover_client_host=0

4. 检查宿主机防火墙规则 #

确保宿主机的9003端口允许容器访问：

# 临时开放9003端口
sudo ufw allow 9003/tcp
# 永久生效
sudo ufw allow 9003/tcp

5. 验证PhpStorm监听状态 #

• 确保PhpStorm右上角的调试监听按钮（电话图标）处于绿色开启状态
• 检查Settings > Languages & Frameworks > PHP > Debug中，Debug port设置为9003，且Allow incoming connections已勾选

三、补充验证步骤 #

普通用户重启Docker Compose后：

1. 访问页面触发xdebug_info()，查看Debugger模块下的Connected Client信息
2. 使用PhpStorm的Validate Debugger Configuration工具，选择Remote Web Server模式，输入容器内的项目路径（/var/www/html）进行验证

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