PHPStorm怎么配置xdebug工具并使用？

封面图 • 2025-05-22 • PHP

在 PHPStorm 中配置 Xdebug 工具是一个常见的开发任务，用于调试 PHP 应用程序。以下是详细的步骤：

### 1. 安装 Xdebug 扩展

#### 在 Linux 上安装 Xdebug：
```bash
sudo pecl install xdebug
```

然后编辑 `php.ini` 文件（通常位于 `/etc/php/7.x/cli/php.ini` 或 `/etc/php/7.x/apache2/php.ini`），添加以下内容：

```ini
[xdebug]
zend_extension=/usr/lib/php/20210902/xdebug.so
xdebug.remote_enable=1
xdebug.remote_host=localhost
xdebug.remote_port=9003
xdebug.remote_handler=dbgp
xdebug.remote_mode=req
xdebug.remote_autostart=1
xdebug.remote_connect_back=1
xdebug.remote_log=/tmp/xdebug.log
```

重启你的 Web 服务器（例如 Apache 或 Nginx）。

#### 在 Windows 上安装 Xdebug：
1. 下载对应的 Xdebug DLL 文件（可以从 [Xdebug 官方网站](https://xdebug.org/download) 下载）。
2. 将下载的文件放入 PHP 的扩展目录中。
3. 编辑 `php.ini` 文件，添加以下内容：

```ini
[xdebug]
zend_extension="C:\path\to\xdebug.dll"
xdebug.remote_enable=1
xdebug.remote_host=localhost
xdebug.remote_port=9003
xdebug.remote_handler=dbgp
xdebug.remote_mode=req
xdebug.remote_autostart=1
xdebug.remote_connect_back=1
xdebug.remote_log="C:\path\to\xdebug.log"
```

4. 重启 Web 服务器。

### 2. 配置 PHPStorm

#### 启动 PHPStorm 并打开项目：
1. 打开 PHPStorm 并加载你的项目。
2. 点击顶部菜单栏的 **File > Settings**（或者 **PHPStorm > Preferences** 在 macOS 上）。
3. 导航到 **Languages & Frameworks > PHP > Debug**。
   - 确保 Xdebug 的端口号设置为默认的 `9003`（这是 Xdebug 3 的默认端口）。
4. 再次导航到 **Languages & Frameworks > PHP > Servers**。
   - 点击左上角的加号按钮，添加一个新的服务器配置。
   - 输入服务器名称（例如 `localhost`）。
   - 设置 Host 为 `localhost`。
   - 设置 Port 为你运行的 Web 服务器的端口（例如 80 或 443）。
   - 勾选 **Use path mappings** 选项，并设置本地路径和远程路径的映射（如果需要）。
5. 返回到 **Languages & Frameworks > PHP > Debug**，确保 **DBGp Proxy** 的 Host 和 Port 设置正确。
6. 点击顶部菜单栏的 **Run > Edit Configurations**。
   - 点击左上角的加号按钮，选择 **PHP Web Page**。
   - 设置 URL 为你项目的入口页面（例如 `http://localhost/your_project/index.php`）。
   - 在 **Debugger** 下拉菜单中选择你刚刚创建的服务器配置。

### 3. 启动调试会话

1. 在 PHP 文件中设置断点：点击代码行号左侧的空白区域即可设置断点。
2. 点击顶部菜单栏的绿色虫子图标（Debug 按钮）。
3. PHPStorm 会启动一个浏览器窗口，并附加到你的应用程序上。
4. 当程序执行到断点时，它会暂停执行，允许你在 PHPStorm 中检查变量、调用堆栈等。

### 4. 常见问题排查

- **无法连接到 Xdebug**：
  - 检查 Xdebug 是否正确安装并启用。
  - 确保 PHPStorm 的服务器配置和 Xdebug 的端口一致。
  - 查看 Xdebug 日志文件（`xdebug.remote_log`）以获取更多信息。

- **断点未命中**：
  - 确保 `xdebug.remote_autostart=1` 或者在请求中包含 `XDEBUG_SESSION_START` 参数。
  - 确保断点设置正确。

通过以上步骤，你应该能够在 PHPStorm 中成功配置和使用 Xdebug 进行 PHP 调试。