本文旨在解决在使用 NAT 网络模式的虚拟机中，通过 Xdebug 调试 PHP 应用时遇到的连接问题。文章将详细介绍 Xdebug 的配置，以及 VS Code 调试器的设置，并提供排查连接错误的步骤，帮助开发者顺利进行远程调试。
Xdebug 配置
在使用 Xdebug 调试虚拟机中的 PHP 应用时，正确的配置至关重要。以下是关键配置项的说明：
- zend_extension=xdebug.so: 指定 Xdebug 扩展的路径。确保路径正确，并且 Xdebug 扩展已正确安装。
- xdebug.mode = debug: 启用调试模式。
- xdebug.client_host: 指定调试客户端（通常是你的主机）的 IP 地址。这是配置中最关键的部分，也是最容易出错的地方。 在 NAT 网络模式下，这个地址应该是主机在虚拟机网络中的 IP 地址。通常情况下，虚拟机网关的 IP 地址就是主机的 IP 地址。
- xdebug.client_port: 指定调试客户端监听的端口。常用的端口是 9003 或 9000。
- xdebug.log: 指定 Xdebug 日志文件的路径。可以用于排查连接问题。
- xdebug.discover_client_host = false: 禁用自动发现客户端主机的功能。在 NAT 环境下，手动配置 xdebug.client_host 更可靠。
示例配置：
zend_extension=xdebug.so xdebug.mode = debug xdebug.client_host = 192.168.122.1 ; 主机在虚拟机网络中的IP地址 xdebug.client_port = 9003 xdebug.log=/var/log/xdebug.log xdebug.discover_client_host = false
获取主机在虚拟机网络中的 IP 地址：
立即学习“PHP免费学习笔记（深入）”；
一种方法是在虚拟机中执行 echo $SSH_CLIENT | awk '{ print }' 命令。另一种方法是查看虚拟机网关的 IP 地址。
VS Code 调试器配置
VS Code 需要配置 launch.json 文件才能与 Xdebug 建立连接。以下是一个示例配置：
{
"version": "0.2.0",
"configurations": [
{
"name": "Listen for Xdebug",
"type": "php",
"request": "launch",
"port": 9003, // 确保与 xdebug.client_port 相同
"hostname": "192.168.122.1", // 主机在虚拟机网络中的IP地址
"pathMappings": {
"/var/www/clients/client1/web4/web": "${workspaceRoot}" // 虚拟机中的项目路径与本地项目路径的映射
}
}
]
}- port: 指定 VS Code 监听的端口。必须与 xdebug.client_port 的值相同。
- hostname: 指定要连接的主机名。 重要：通常情况下，应该将此字段留空，或者设置为你的机器在虚拟机网络中的IP地址(例如192.168.122.1)。 错误的 hostname 配置是导致连接失败的常见原因。
- pathMappings: 指定虚拟机中的项目路径与本地项目路径的映射。这使得 VS Code 能够正确地显示断点和变量。
常见问题及解决方法
-
EADDRNOTAVAIL 错误： 这个错误通常表示 VS Code 无法在指定的 IP 地址和端口上监听。检查以下几点：
- 确保 hostname 配置正确。
- 确保指定的端口没有被其他程序占用。
- 尝试重启 VS Code 或计算机。
-
Connection refused 错误： 这个错误表示 Xdebug 无法连接到 VS Code。检查以下几点：
- 确保 Xdebug 配置正确，特别是 xdebug.client_host 和 xdebug.client_port。
- 确保防火墙没有阻止 Xdebug 连接到 VS Code。
- 检查 Xdebug 日志文件，查看是否有错误信息。
路径映射错误： 如果断点无法正确地触发，或者变量显示不正确，检查 pathMappings 配置是否正确。确保虚拟机中的项目路径与本地项目路径的映射是正确的。
总结
通过正确的配置 Xdebug 和 VS Code 调试器，可以轻松地调试 NAT 虚拟机中的 PHP 应用。关键在于理解 NAT 网络模式下的 IP 地址和端口映射，并确保所有配置项都正确。如果遇到连接问题，仔细检查配置和日志文件，通常可以找到问题的根源。
