如何在 ServBay 中启用和配置 Xdebug 模块

ServBay 作为一个功能强大的本地 Web 开发环境，为 PHP 开发者预集成了 Xdebug 调试和分析工具。启用 Xdebug 可以显著提升 PHP 应用的开发效率，帮助您更便捷地进行代码调试、性能分析和代码覆盖率检测。本文将详细介绍如何在 ServBay 中启用和配置 Xdebug，并指导如何在主流集成开发环境（IDE）中进行集成。

Xdebug 模块概述

Xdebug 是一个功能丰富的 PHP 扩展，专为 PHP 代码的调试和分析而设计。ServBay 预集成了 Xdebug，免去了开发者手动编译和安装的复杂过程，使得启用和配置变得非常简单。

Xdebug 的主要功能

断点调试: 允许在代码的特定行设置断点，程序执行到断点时暂停，开发者可以检查当前变量状态、调用堆栈等，逐行执行代码。
步进调试: 支持单步执行代码（Step Over）、进入函数（Step Into）、跳出函数（Step Out），方便跟踪程序执行流程。
变量监视: 在调试过程中实时查看局部和全局变量的值。
堆栈跟踪: 在发生错误或异常时，提供详细的函数调用堆栈信息，帮助快速定位问题源头。
性能分析 (Profiling): 生成代码执行的性能报告，帮助识别性能瓶颈。
代码覆盖率检测 (Code Coverage): 测量测试代码覆盖到的程序代码比例，用于评估测试的有效性。

ServBay 内置的 Xdebug 版本与端口映射

ServBay 为不同的 PHP 版本预装了相应的 Xdebug 模块。需要注意的是，每个 PHP 版本对应的 Xdebug 监听端口是独立的，且与 PHP 版本号相关联，这对于在 IDE 中配置调试器至关重要。

PHP 版本	预装 Xdebug 版本	默认 Xdebug 监听端口
PHP 5.6	Xdebug 2.5.5	39056
PHP 7.0	Xdebug 2.5.5	39070
PHP 7.1	Xdebug 2.5.5	39071
PHP 7.2	Xdebug 3.1.6	39072
PHP 7.3	Xdebug 3.1.6	39073
PHP 7.4	Xdebug 3.1.6	39074
PHP 8.0	Xdebug 3.3.1	39080
PHP 8.1	Xdebug 3.4.0	39081
PHP 8.2	Xdebug 3.4.0	39082
PHP 8.3	Xdebug 3.4.0	39083
PHP 8.4	Xdebug 3.4.0	39084
PHP 8.5	Xdebug 3.4.0	39085

端口规则

Xdebug 的默认监听端口规则是 39000 + PHP 副版本号。例如，PHP 8.3 的端口是 39000 + 83 = 39083，PHP 7.4 的端口是 39000 + 74 = 39074。理解此规则有助于您快速确定不同 PHP 版本的 Xdebug 端口。

如何启用 Xdebug 模块

在 ServBay 中启用 Xdebug 模块非常方便，推荐通过 ServBay 的图形用户界面（GUI）进行操作。您也可以选择手动编辑配置文件。

通过 ServBay GUI 启用 Xdebug

这是最简单快捷的方法。

打开 ServBay 应用界面。
在左侧导航栏中，选择 语言 ( Languages)。
展开 PHP 部分，找到您希望启用 Xdebug 的 PHP 版本，例如 PHP 8.3。
点击该版本右侧的 扩展 按钮。
在弹出的扩展列表中，找到 Xdebug 模块。
点击 Xdebug 模块左侧的开关，将其状态从关闭切换到打开。
根据需要修改参数
点击界面底部的 保存 按钮。
ServBay 将会自动重启 PHP 进程并加载模块。

图示：在扩展中启用 Xdebug

验证 Xdebug 模块是否成功加载

最可靠的验证方法是通过 phpinfo() 函数查看 PHP 的配置信息。

在 ServBay 网站根目录（默认 /Applications/ServBay/www）下创建一个简单的 PHP 文件，例如 phpinfo.php。
在 phpinfo.php 文件中添加以下内容：
php
```
<?php
phpinfo();
?>
```
1
2
3
通过浏览器访问该文件，例如 https://servbay.demo/phpinfo.php (请替换 servbay.demo 为您在 ServBay 中配置的对应网站域名)。
在输出的 phpinfo 页面中搜索 "Xdebug"。如果 Xdebug 模块已成功加载，您将看到一个独立的 "Xdebug" 配置部分，其中包含其版本信息和各项配置参数。

图示：在 phpinfo 输出中查找 Xdebug 信息

在 IDE 中配置 Xdebug 进行调试

启用 Xdebug 只是第一步，要在 IDE 中进行断点调试，还需要在 IDE 中配置 PHP 解释器、调试器以及服务器映射。以下以 PHPStorm 和 Visual Studio Code (VS Code) 为例进行说明。

在 PHPStorm 中配置 Xdebug

PHPStorm 对 Xdebug 的支持非常完善。

打开 PHPStorm 设置: 启动 PHPStorm，并通过菜单 File -> Settings (Windows/Linux) 或 PHPStorm -> Preferences (macOS) 打开设置窗口。
配置 PHP CLI 解释器:
- 导航到 Languages & Frameworks -> PHP。
- 在 CLI Interpreter 部分，点击右侧的 ... 按钮。
- 在弹出的窗口中，点击 + 号添加新的本地解释器。
- 选择 ServBay 中对应 PHP 版本的 CLI 可执行文件路径，例如 /Applications/ServBay/package/php/8.3/8.3.7/bin/php (请注意版本号可能因 ServBay 更新而不同，以您的 ServBay 安装目录为准)。
- PHPStorm 会自动检测该解释器的版本和扩展信息，包括 Xdebug。
- 点击 OK 保存解释器配置。 图示：在 PHPStorm 中配置 ServBay 的 PHP CLI 解释器
配置 Xdebug 调试参数:
- 导航到 Languages & Frameworks -> PHP -> Debug。
- 在 Xdebug 部分，设置 Debug Port 为您在 ServBay 中启用的 PHP 版本对应的 Xdebug 监听端口（例如，PHP 8.3 使用 39083）。确保此端口与 xdebug.client_port 配置一致。
- 勾选 Can accept external connections 选项。
- 点击 Apply 然后点击 OK 保存设置。 图示：在 PHPStorm 中配置 Xdebug 监听端口
配置 PHP Web 服务器映射:
- 导航到 Languages & Frameworks -> PHP -> Servers。
- 点击右侧的 + 号添加一个新的服务器配置。
- 设置服务器名称（例如 ServBay Localhost）。
- 设置 Host 为您在 ServBay 中配置的网站域名（例如 servbay.demo）。
- 设置 Port 为您网站使用的端口，通常是 443 (HTTPS) 或 80 (HTTP)。
- 设置 Debugger 为 Xdebug。
- 在下方的 Use path mappings 选项前打勾。
- 配置本地项目路径 (Absolute path to local source) 与服务器上对应路径 (Absolute path on the server) 的映射关系。通常，如果您将项目放在 /Applications/ServBay/www/myproject，并且通过 https://servbay.demo/ 访问，那么本地路径 /Applications/ServBay/www/myproject 应该映射到服务器路径 /。如果您通过 https://myproject.servbay.demo/ 访问，且项目根目录是 /Applications/ServBay/www/myproject，则本地路径 /Applications/ServBay/www/myproject 映射到服务器路径 /。确保路径映射正确是 Xdebug 正常工作的关键。
- 点击 OK 保存设置。 图示：在 PHPStorm 中配置服务器和路径映射
启动调试会话:
- 在 PHPStorm 中打开您想要调试的 PHP 项目文件。
- 在代码行号左侧的空白区域点击，设置断点（红色圆点）。
- 点击 PHPStorm 顶部工具栏中的 Start Listening for PHP Debug Connections 按钮（小虫子图标）。该按钮会变为绿色，表示 PHPStorm 正在监听 Xdebug 连接。
- 在浏览器中访问您的 PHP 应用（例如 https://servbay.demo/index.php）。
- 如果一切配置正确，Xdebug 会自动连接到 PHPStorm 并在您设置的断点处暂停执行，此时您就可以在 PHPStorm 中进行调试了。 图示：在 PHPStorm 中启动 Xdebug 监听

在 Visual Studio Code (VS Code) 中配置 Xdebug

VS Code 是另一个流行的代码编辑器，通过安装扩展可以很好地支持 Xdebug 调试。

安装 PHP Debug 扩展:
- 打开 VS Code。
- 切换到扩展视图 (Ctrl+Shift+X 或 Cmd+Shift+X)。
- 搜索 "PHP Debug" 并安装 by Felix Becker 的扩展。

配置 launch.json:

打开您的 PHP 项目文件夹。
切换到运行和调试视图 (Ctrl+Shift+D 或 Cmd+Shift+D)。
点击顶部工具栏的齿轮图标，选择 "PHP"。这会在项目根目录下的 .vscode 文件夹中创建一个 launch.json 文件。
编辑 launch.json 文件，通常会包含一个名为 "Listen for Xdebug" 的配置。确保其中的 port 参数与您在 ServBay 中启用的 PHP 版本对应的 Xdebug 监听端口一致（例如，PHP 8.3 使用 39083）。

配置路径映射 (Path Mapping): 这是 VS Code 中 Xdebug 调试的关键一步。在 launch.json 中找到或添加 pathMappings 配置项。它将 ServBay 服务器上的项目路径映射到您本地文件系统中的项目路径。

json

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 39083, // 根据您的 PHP 版本修改此端口
            "pathMappings": {
                // 将 ServBay 网站根目录下的项目路径映射到本地文件系统路径
                // 例如，如果您的项目在 /Applications/ServBay/www/myproject
                // 且通过 https://servbay.demo/ 访问，则服务器根目录 '/' 对应本地项目根目录
                "/": "${workspaceRoot}"
                // 如果您的项目在 /Applications/ServBay/www/myproject
                // 且通过 https://myproject.servbay.demo/ 访问 (子域名对应子目录)
                // 则服务器根目录 '/' 对应本地项目根目录
                // "/": "${workspaceRoot}" // 同样适用
            }
        },
        {
            "name": "Launch currently open script",
            "type": "php",
            "request": "launch",
            "program": "${file}",
            "cwd": "${fileDirname}",
            "port": 39083 // 根据您的 PHP 版本修改此端口
        }
    ]
}

请根据您的项目结构和 ServBay 网站配置调整 pathMappings。${workspaceRoot} 通常指向您在 VS Code 中打开的项目文件夹的根目录。

启动调试会话:
- 在 VS Code 中打开您的 PHP 项目文件。
- 在代码行号左侧点击，设置断点（红色圆点）。
- 切换到运行和调试视图 (Ctrl+Shift+D 或 Cmd+Shift+D)。
- 在顶部的调试配置下拉菜单中选择您刚才配置的 "Listen for Xdebug"。
- 点击绿色的启动调试按钮。VS Code 状态栏会变为橙色，表示正在监听 Xdebug 连接。
- 在浏览器中访问您的 PHP 应用。如果配置正确，Xdebug 会连接到 VS Code 并在断点处暂停。

常见问题 (FAQ)

Q: Xdebug 模块在 phpinfo() 中没有显示？
- A: 确保您已经在 ServBay GUI 或手动编辑 xdebug.ini 中启用了 Xdebug。
- 确保您已经重启了对应的 PHP 服务。
- 检查 xdebug.ini 文件路径是否正确，以及 zend_extension = xdebug.so 行是否已取消注释。
- 检查 ServBay 的日志文件 (/Applications/ServBay/logs/php/<version>/error.log) 是否有 Xdebug 加载失败的错误信息。
Q: 在 IDE 中设置了断点，但程序没有停下来？
- A: 确保您的 IDE 正在监听 Xdebug 连接（PHPStorm 的小虫子图标变绿，VS Code 状态栏变橙）。
- 检查 IDE 中配置的 Xdebug 监听端口是否与 ServBay 中 xdebug.client_port 配置以及该 PHP 版本对应的默认端口一致。
- 检查 IDE 中的路径映射 (Path Mapping) 是否正确配置，确保服务器上的文件路径能正确映射到您本地的项目文件。这是最常见的配置错误。
- 检查您的防火墙设置，确保没有阻止 IDE 监听 Xdebug 端口（默认为 390xx 系列端口）。
- 如果在 xdebug.ini 中使用了 xdebug.start_with_request=trigger，请确保您的浏览器或请求中包含了触发器（例如使用浏览器 Xdebug 助手扩展，或在 URL 中添加 ?XDEBUG_TRIGGER=1）。
Q: Xdebug 连接在一段时间后断开？
- A: 检查 xdebug.ini 中的 xdebug.remote_autostart 或 xdebug.start_with_request 参数。如果设置为 yes，可能会导致每个请求都尝试启动调试。建议使用 trigger 模式。
- 检查 IDE 的调试设置，有时 IDE 会有连接超时设置。

结论

ServBay 通过预集成和简化的配置流程，极大地降低了 PHP 开发者启用和使用 Xdebug 的门槛。无论是通过直观的 GUI 还是手动编辑配置文件，您都可以快速在 ServBay 中不同版本的 PHP 环境下启用 Xdebug。结合 PHPStorm、VS Code 等主流 IDE 的强大调试功能，您可以更高效地进行 PHP 代码调试、性能调优和质量保障，从而显著提升开发效率。掌握 ServBay 与 Xdebug 的结合使用，将是您本地 PHP 开发工作流中的利器。

如何在 ServBay 中启用和配置 Xdebug 模块 ​

Xdebug 模块概述 ​

Xdebug 的主要功能 ​

ServBay 内置的 Xdebug 版本与端口映射 ​

如何启用 Xdebug 模块 ​

通过 ServBay GUI 启用 Xdebug ​

验证 Xdebug 模块是否成功加载 ​

在 IDE 中配置 Xdebug 进行调试 ​

在 PHPStorm 中配置 Xdebug ​

在 Visual Studio Code (VS Code) 中配置 Xdebug ​

常见问题 (FAQ) ​

结论 ​