在VS Code中配置PHP开发环境并启用Xdebug调试需完成三步：安装PHP（CLI）、配置Xdebug扩展、使用PHP Debug插件连接；关键在于路径正确、端口一致（默认9003）、php.ini与launch.json端口匹配、pathMappings映射准确。
在 VS Code 中配置 PHP 开发环境并启用 Xdebug 调试，核心是三件事：装好 PHP（含 CLI）、配对 Xdebug 扩展、用 VS Code 的 PHP Debug 插件连接调试器。只要路径对、端口通、配置准，断点就能停住。
安装并验证本地 PHP 环境
VS Code 本身不运行 PHP，它依赖你系统已安装的 PHP 解释器。先确认命令行能调用 php：
- 终端输入 php -v，看到版本号（如 8.1+）说明已安装
- 输入 php -m | grep xdebug，若无输出，说明 Xdebug 还没装或没启用
- 推荐用 windows.php.net（Windows）或 brew install php（macOS）获取干净 PHP 包，避免 MAMP/XAMPP 带来的路径混乱
安装并配置 Xdebug（以 PHP 8.0+ 为例）
Xdebug 3 与旧版配置差异大，别套用网上 Xdebug 2 的 php.ini 写法。正确步骤如下：
- 用 php -v 查看 PHP 版本和架构（如 Thread Safe 或 Non-Thread Safe），去 xdebug.org/download 下载对应 .dll（Windows）或 .so（macOS/Linux）文件
- 把下载的 xdebug.so 或 php_xdebug.dll 放到 PHP 的 ext/ 目录下
- 编辑 php.ini（用 php --ini 找准确路径），在末尾添加：
[xdebug] zend_extension=xdebug.so xdebug.mode=debug xdebug.start_with_request=yes xdebug.client_host=127.0.0.1 xdebug.client_port=9003 xdebug.log=/tmp/xdebug.log ; 临时开启，查连不上时看日志
注意：xdebug.client_port 默认是 9003（不是旧版的 9000），VS Code 插件默认也连这个端口，保持一致才不会“断点不触发”。
立即学习“PHP免费学习笔记（深入）”；
在 VS Code 中安装插件并配置 launch.json
打开 VS Code，装两个关键插件：
- PHP Intelephense（代码提示、跳转、错误检查）
- PHP Debug（由 Felix Becker 维护，支持 Xdebug 3）
然后在项目根目录创建 .vscode/launch.json（可通过命令面板 → “Debug: Open launch.json” 自动生成）：
{
"version": "0.2.0",
"configurations": [
{
"name": "Listen for Xdebug",
"type": "php",
"request": "launch",
"port": 9003,
"pathMappings": {
"/var/www/html": "${workspaceFolder}"
}
}
]
}
</font>
<p>重点说明：</p>
<ul>
<li><strong>port 必须和 php.ini 里的 xdebug.client_port 一致</strong></li>
<li><strong>pathMappings</strong> 是关键！左边是服务器上 PHP 实际运行的绝对路径（比如 Docker 容器里是 /var/www/html），右边是本地项目路径。本地开发没容器就写成 <strong>"${workspaceFolder}": "${workspaceFolder}"</strong></li>
<li>启动调试前，先点左下角绿色 ▶️ 启动监听，再在浏览器访问脚本（如 http://localhost/test.php），断点才会生效</li>
</ul>
<H3>验证调试是否成功</H3>
<p>写个简单 test.php：</p>
<font size="2">
<pre class="brush:php;toolbar:false;">
<?php
$x = 1;
var_dump($x); // 在这行左侧灰色区域点击设断点
echo "hello";
?>
操作流程：
- VS Code 中按 Ctrl+Shift+D（Windows/macOS）打开调试面板，选中 “Listen for Xdebug”
- 点绿色 ▶️ 启动监听（状态栏出现 “Xdebug listening”）
- 浏览器打开 http://localhost/test.php（确保 PHP 服务正在运行）
- VS Code 自动停在断点，变量窗显示 $x=1，可单步、续行、查看堆栈——说明全通了
如果没反应，优先检查：php -m 是否列出 xdebug、php --ini 确认改的是真 php.ini、netstat -an | grep 9003 看端口是否被占用。
基本上就这些。不复杂但容易忽略 pathMappings 和端口一致性，调通一次，后续项目复制配置就行。
