Docker + Phalcon + PhpStorm + Xdebug 2/3 完整配置文档

一、先判断你是 Xdebug 2 还是 Xdebug 3

执行：Bash

php -i | grep xdebug

判定规则

• 有 mode/ xdebug.client_host → Xdebug 3
• 有 remote_host/ xdebug.remote_port → Xdebug 2

二、Xdebug 2 完整配置（你现在在用的）

1、配置文件路径

/usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini

2、完整配置（直接复制覆盖）

zend_extension=xdebug.soxdebug.idekey = PHPSTORM xdebug.remote_enable = 1 xdebug.remote_autostart = 1 xdebug.remote_host = host.docker.internal xdebug.remote_port = 9000 xdebug.remote_connect_back = 0xdebug.overload_var_dump = 0

3、重启 PHP:Bash

pkill php-fpm && php-fpm -D

4、验证:Bash

php -i | grep remote

5、必须出现：

remote_enable => On remote_autostart => On remote_host => host.docker.internal remote_port => 9000

三、Xdebug 3 完整配置（新版推荐）

1、配置文件

/usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini

2、完整配置

zend_extension=xdebug.soxdebug.mode = debug xdebug.start_with_request = yes xdebug.client_host = host.docker.internal xdebug.client_port = 9003 xdebug.idekey = PHPSTORMxdebug.overload_var_dump = Off xdebug.format_output = Off

3、重启 PHP:Bash

pkill php-fpm && php-fpm -D

4、验证:Bash

php -i | grep xdebug.mode php -i | grep client_host

四、PhpStorm 通用配置（Xdebug 2 / 3 都适用）

1. 配置 Server（最关键）

File → Settings → PHP → Servers

• Name: docker
• Host: localhost
• Port: 你的项目端口（80/8080）
• Debugger: Xdebug
• ✅ Use path mappings必须勾选

      路径映射规则

本地项目目录      →    Docker 容器内项目目录 ———————————————— 例如： D:\work\project   →    /www

2. 配置 Debug 端口

File → Settings → PHP → Debug

• Xdebug 2 → 端口：9000
• Xdebug 3 → 端口：9003
• ✅ Can accept external connections勾选

3. 开启监听

点击右上角 📞 电话图标 点亮
或：Run → Start Listening for PHP Debug Connections

 

五、Docker 环境必须记住的 3 条铁律

1. host 必须写：docker.internal
2. 路径映射必须配对，否则断点不进
3. Xdebug 2 ≠ Xdebug 3 配置不通用

 

六、Postman 触发调试（通用）

1、请求 Headers 添加：

Cookie: XDEBUG_SESSION=PHPSTORM

2、发送请求 → 自动断在 PhpStorm

 

七、常见问题 1 分钟排查

1. 断点不进

• 路径映射错
• 端口不匹配（9000 / 9003）
• 没开监听
• docker.internal写错

2. 接口返回 < 乱码

加配置：

xdebug.overload_var_dump = 0

3. Xdebug 报错：already loaded

只保留一个 .ini 文件，删除 php.ini 里的 xdebug 配置

八、最简速查版（直接背）

版本	端口	host	配置文件关键词
Xdebug 2	9000	host.docker.internal	remote_host
Xdebug 3	9003	host.docker.internal	client_host