VSCode 中配置 Xdebug

封面图 • 2026-04-25 • PHP

在 VSCode 中配置 Xdebug 可以帮助你进行 PHP 的调试。以下是详细的步骤，适用于 Windows、macOS 和 Linux 系统。

---

## ✅ 前提条件

1. **安装 PHP**（确保已安装并配置好）
2. **安装 Xdebug**（PHP 扩展）
3. **安装 VSCode**
4. **安装 PHP Debug 扩展**（由 Microsoft 提供）

---

## 🧰 步骤一：安装 Xdebug

### 1. 检查当前 PHP 版本
```bash
php -v
```

### 2. 安装 Xdebug

#### 使用 `pecl` 安装（推荐）：
```bash
pecl install xdebug
```

或者根据你的 PHP 版本下载对应的 [Xdebug](https://xdebug.org/download) 包，并手动添加到 `php.ini`。

#### 添加 Xdebug 到 `php.ini` 文件中：

```ini
[xdebug]
zend_extension="path/to/xdebug.so"  ; macOS/Linux
; zend_extension="path/to/php_xdebug.dll" ; Windows
xdebug.mode=develop
xdebug.client_host=localhost
xdebug.client_port=9003
xdebug.log=/tmp/xdebug.log
```

> 注意：路径需要根据你实际的 PHP 安装路径来填写。

### 3. 重启 Web 服务器（如 Apache 或 Nginx）

---

## 🛠️ 步骤二：安装 VSCode 的 PHP Debug 扩展

1. 打开 VSCode。
2. 进入扩展商店（快捷键 `Ctrl+Shift+X`）。
3. 搜索 `PHP Debug`，安装由 Microsoft 提供的扩展。

---

## 🔧 步骤三：配置 VSCode 的 `launch.json`

1. 在 VSCode 中打开你的 PHP 项目。
2. 点击左侧边栏的“运行和调试”图标（或按 `Ctrl+Shift+D`）。
3. 点击“创建 launch.json 文件”。
4. 选择 `PHP` 作为环境。

生成的 `launch.json` 内容如下：

```json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Listen for XDebug",
      "type": "php",
      "request": "launch",
      "port": 9003,
      "pathMappings": {
        "/var/www/html": "${workspaceFolder}"
      }
    }
  ]
}
```

> 如果你使用的是其他路径，请修改 `pathMappings`。

---

## 🔄 步骤四：启动调试

1. 在代码中设置断点（点击行号左侧）。
2. 点击“开始调试”按钮（绿色三角形）。
3. 访问你的 PHP 页面（例如通过浏览器访问 `http://localhost/yourfile.php`）。
4. 当程序执行到断点时，VSCode 会暂停并进入调试模式。

---

## 🧪 测试 Xdebug 是否正常工作

你可以创建一个测试文件 `test.php`：

```php
<?php
$x = 10;
$y = 20;
$result = $x + $y;
echo $result;
?>
```

然后在 VSCode 中设置断点，运行调试，查看是否能正常停在断点处。

---

## ⚠️ 常见问题

### 1. Xdebug 不工作怎么办？

- 检查 `phpinfo()` 中是否有 Xdebug 模块。
- 确保 `xdebug.client_host` 设置为 `localhost` 或你的 IP 地址。
- 确保 `xdebug.port` 和 `launch.json` 中的 `port` 一致（默认是 `9003`）。
- 检查防火墙或端口占用。

### 2. VSCode 调试器无法连接？

- 确保 `xdebug.mode=debug` 或 `xdebug.mode=develop`。
- 确保 PHP 配置正确，没有语法错误。
- 尝试使用 `xdebug.start_with_request=1` 来自动启动调试。

---

## 📌 总结

| 步骤 | 说明 |
|------|------|
| 安装 Xdebug | 通过 `pecl` 或手动安装 |
| 配置 `php.ini` | 添加 Xdebug 配置项 |
| 安装 VSCode 扩展 | 安装 `PHP Debug` 扩展 |
| 配置 `launch.json` | 设置调试参数 |
| 启动调试 | 设置断点并运行调试 |

---

如果你需要更具体的配置（比如 Docker、Laravel、Apache/Nginx 等），欢迎继续提问！