Hyper-V环境下如何让虚拟机内Xdebug连接宿主机PhpStorm？

环境背景 #

• 宿主机：Windows，Hyper-V默认交换机IP为172.17.96.1
• 虚拟机：Ubuntu（Vagrant部署），搭载PHP-FPM + Xdebug 2，IP为172.17.111.24
• 基础网络状态：宿主机可SSH/访问虚拟机Web服务，虚拟机可联网且能ping通宿主机172.17.96.1，但Xdebug无法建立调试连接

错误现象 #

1. Xdebug日志：

[2641] Log opened at 2022-09-15 12:59:46
[2641] I: Checking remote connect back address.
[2641] I: Checking header 'HTTP_X_FORWARDED_FOR'.
[2641] I: Checking header 'REMOTE_ADDR'.
[2641] I: Remote address found, connecting to 172.17.96.1:9000.
[2645] E: Time-out connecting to client (Waited: 200 ms). :-
[2645] Log closed at 2022-09-15 12:59:46

2. 宿主机监听状态：netstat -a显示PhpStorm已监听0.0.0.0:9000
3. 虚拟机telnet测试：执行telnet 172.17.96.1 9000一直卡在Trying状态

解决步骤 #

1. 配置Windows防火墙入站规则 #

Windows防火墙默认会拦截Hyper-V虚拟机的入站连接，即使端口已被监听：

• 打开「Windows Defender防火墙」→「高级设置」→「入站规则」
• 新建规则：
  • 规则类型：选择「端口」
  • 协议和端口：TCP，特定本地端口填9000（Xdebug 2默认端口）
  • 操作：选择「允许连接」
  • 配置文件：勾选「域」「专用」「公网」（或根据实际网络环境选择）
  • 名称：自定义规则名称，比如「允许Xdebug虚拟机调试连接」

2. 修正Xdebug配置 #

修改虚拟机内的Xdebug配置文件（路径示例：/etc/php/7.x/fpm/conf.d/20-xdebug.ini，根据PHP版本调整），确保参数如下：

xdebug.remote_enable = 1
xdebug.remote_host = 172.17.96.1  # 直接指定宿主机Hyper-V交换机IP，避免反向解析问题
xdebug.remote_port = 9000
xdebug.remote_connect_back = 0  # 关闭反向连接逻辑，强制使用指定的remote_host
xdebug.remote_autostart = 1  # 可选，自动触发调试会话
xdebug.remote_log = /var/log/xdebug.log  # 保留日志用于后续排查

修改后重启PHP-FPM服务：

sudo service php7.x-fpm restart

3. 验证PhpStorm调试设置 #

• 打开PhpStorm→「File」→「Settings」→「Languages & Frameworks」→「PHP」→「Debug」
  • 确认「Debug port」为9000，与Xdebug配置一致
  • 勾选「Allow incoming connections」
• 配置服务器映射：
  • 进入「Servers」选项，新建服务器，名称自定义，主机填虚拟机IP172.17.111.24，端口80
  • 勾选「Use path mappings」，将宿主机项目目录映射到虚拟机内的对应路径（例如：宿主机D:/projects/test → 虚拟机/var/www/test）

4. 测试连接有效性 #

在虚拟机内重新执行telnet测试：

telnet 172.17.96.1 9000

如果能成功进入telnet交互界面，说明网络通路已打通。此时启动PhpStorm的调试监听按钮，触发PHP请求即可进入断点调试。

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