# PHP Xdebug 配置解决方案

## 问题描述

在 PHPStudy 环境中使用 PHP 8.2.9 NTS 版本时，debug设置

1. Xdebug v3.x 配置参数已过时，使用 v2.x 的参数名

 

### 2. 更新 Xdebug 配置（v2.x → v3.x）

 

**新配置（v3.x）**:

```ini

[Xdebug]

zend_extension=C:/phpstudy_pro/Extensions/php/php8.2.9nts/ext/php_xdebug.dll

xdebug.mode=debug

xdebug.start_with_request=yes

xdebug.client_host=127.0.0.1

xdebug.client_port=9003

xdebug.output_dir=C:/phpstudy_pro/Extensions/php_log/php8.2.9nts.xdebug

xdebug.profiler_enable=0

```

### 3. Xdebug v3.x 参数对照表

| v2.x 参数 | v3.x 参数 | 说明 |

|----------|----------|------|

| `xdebug.profiler_output_dir` | `xdebug.output_dir` | 输出目录 |

| `xdebug.remote_enable` | `xdebug.mode=debug` | 启用调试模式 |

| `xdebug.remote_autostart` | `xdebug.start_with_request=yes` | 自动启动调试 |

| `xdebug.remote_host` | `xdebug.client_host` | 客户端主机地址 |

| `xdebug.remote_port` | `xdebug.client_port` | 客户端端口（改为 9003）|

### 4. 重启 PHPStudy

修改配置后需要：

1. 完全关闭 PHPStudy

2. 重新启动 PHPStudy

3. 重启相关服务

### 5. 验证配置

运行命令检查：

```bash

php -v

```

应该不再看到警告信息。

---

## VSCode 调试配置

### 1. 安装 VSCode 扩展

- 安装 **PHP Debug** 扩展（由 Felix Becker 开发）

### 2. 创建 launch.json

**文件位置**: `.vscode/launch.json`

```json

{

    "version": "0.2.0",

    "configurations": [

        {

            "name": "Listen for Xdebug (PHPStudy)",

            "type": "php",

            "request": "launch",

            "port": 9003,

            "pathMappings": {

                "d:/phpstudy_pro/WWW/www.test.dev": "${workspaceFolder}",

                "/www/wwwroot/www.test.dev": "${workspaceFolder}"

            },

            "log": ,

            "externalConsole": false,

            "stopOnEntry": false,

            "env": {

                "XDEBUG_TRIGGER": "VSCODE"

            }

        }

    ]

}

```

### 3. 配置说明

- `port`: Xdebug v3.x 默认使用 9003 端口

- `pathMappings`: 路径映射，将服务器路径映射到本地工作目录

  - Windows 本地路径: `d:/phpstudy_pro/WWW/www.test.dev`

  - Linux 服务器路径: `/www/wwwroot/www.test.dev`

- `log`: 启用日志，方便调试配置问题

- `XDEBUG_TRIGGER`: 环境变量触发 Xdebug

### 4. 开始调试

1. 在 PHP 代码中设置断点

2. 在 VSCode 中按 `F5` 或点击调试按钮

3. 选择 "Listen for Xdebug (PHPStudy)" 配置

4. 在浏览器中访问你的 PHP 页面

5. VSCode 会自动在断点处暂停

---

## 常见问题

### Q: 修改后 `php -v` 仍然显示警告？

**A**: 检查以下几点：

1. 确认修改的是正确的 php.ini 文件

2. 完全重启 PHPStudy（不是仅仅重启 PHP 服务）

3. 清理缓存文件

4. 检查是否有多个 PHP 版本，确认使用的是 8.2.9nts 版本

### Q: 如何确认当前使用的 php.ini 位置？

**A**: 运行命令：

```bash

php --ini

```

会显示加载的配置文件位置。

### Q: Xdebug 连接失败？

**A**: 检查：

1. VSCode PHP Debug 扩展是否已安装

2. 端口 9003 是否被占用

3. 防火墙是否阻止连接

4. 查看 VSCode Debug Console 的日志输出

---

## 环境信息

- **操作系统**: Windows

- **PHP 版本**: 8.2.9 NTS

- **Xdebug 版本**: 3.5.0

- **集成环境**: PHPStudy

---

## 参考资源

- [Xdebug 官方文档](https://xdebug.org/docs/)

- [Xdebug 3.x 迁移指南](https://xdebug.org/docs/upgrade_guide)

- [VSCode PHP Debug 扩展](https://marketplace.visualstudio.com/items?itemName=felixfbecker.php-debug)

---

*文档生成日期: 2025-12-26*