使用 Xdebug 调试 NAT 虚拟机中的 PHP 应用

本文旨在解决在使用 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 $1}' 命令。另一种方法是查看虚拟机网关的 IP 地址。

VS Code 调试器配置

VS Code 需要配置 launch.json 文件才能与 Xdebug 建立连接。以下是一个示例配置：

AppMall应用商店

AI应用商店，提供即时交付、按需付费的人工智能应用服务

56

查看详情

{
    "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 能够正确地显示断点和变量。

常见问题及解决方法

1. EADDRNOTAVAIL 错误： 这个错误通常表示 VS Code 无法在指定的 IP 地址和端口上监听。检查以下几点：

   • 确保 hostname 配置正确。
   • 确保指定的端口没有被其他程序占用。
   • 尝试重启 VS Code 或计算机。

2. Connection refused 错误： 这个错误表示 Xdebug 无法连接到 VS Code。检查以下几点：

   • 确保 Xdebug 配置正确，特别是 xdebug.client_host 和 xdebug.client_port。
   • 确保防火墙没有阻止 Xdebug 连接到 VS Code。
   • 检查 Xdebug 日志文件，查看是否有错误信息。

3. 路径映射错误： 如果断点无法正确地触发，或者变量显示不正确，检查 pathMappings 配置是否正确。确保虚拟机中的项目路径与本地项目路径的映射是正确的。

总结

通过正确的配置 Xdebug 和 VS Code 调试器，可以轻松地调试 NAT 虚拟机中的 PHP 应用。关键在于理解 NAT 网络模式下的 IP 地址和端口映射，并确保所有配置项都正确。如果遇到连接问题，仔细检查配置和日志文件，通常可以找到问题的根源。

以上就是使用 Xdebug 调试 NAT 虚拟机中的 PHP 应用的详细内容，更多请关注php中文网其它相关文章！