VSCode调试PHP需先确保php命令行可用且版本正确，再安装匹配的Xdebug扩展并配置php.ini，接着在VSCode中设置launch.json的端口与路径映射，最后关闭端口冲突、启用浏览器插件并访问带断点的脚本。
VSCode 本身不运行 PHP，它只是编辑器；真正执行和调试 PHP 需要外部环境配合——核心是装好 php 命令行可执行文件，并用 Xdebug 或 OpenTelemetry（PHP 8.3+）对接 VSCode 的调试器。所谓“配置本地服务器”，本质是让 PHP 脚本能被访问、能断点、能看变量。
确认 php 已正确安装并可用
这是所有后续步骤的前提。打开终端输入：
php -v
必须返回 PHP 版本号（如 PHP 8.2.12），且路径不能是 /usr/bin/php（macOS 默认太旧）或 Windows 的 C:\Windows\System32\php.exe（通常不存在）。常见问题：
- Mac 用户用 Homebrew 安装后需确保
brew --prefix php对应的 bin 目录在$PATH中 - Windows 用户推荐使用 官方线程安全（TS）VC17 x64 ZIP 包，解压后把路径加进系统
PATH，再重启 VSCode - VSCode 终端里
php -v成功，但调试时仍报 “Command 'php' not found”？说明 VSCode GUI 启动时没读取 shell 的PATH，需从终端启动：code .
安装并启用 Xdebug（PHP < 8.3）
Xdebug 是目前最稳定的 PHP 调试扩展，但必须与 PHP 版本、线程模型（TS/NTS）、架构（x64/arm64）严格匹配。不要用 pecl install xdebug 自动编译——容易出错。
立即学习“PHP免费学习笔记（深入）”；
- 访问 Xdebug Wizard，粘贴
php --ini输出的配置路径，再运行php -m和php -v结果，它会给出精准的下载链接和php.ini配置项 - Windows 下把
php_xdebug.dll放进ext/目录后，在php.ini末尾加：zend_extension=php_xdebug.dll xdebug.mode=debug xdebug.start_with_request=yes xdebug.client_host=127.0.0.1 xdebug.client_port=9003
- Linux/macOS 类似，但用
zend_extension=xdebug.so，注意路径要绝对（如/usr/local/lib/php/pecl/20220829/xdebug.so） - 改完后务必运行
php -m | grep xdebug确认加载成功，再用php -i | grep xdebug检查配置是否生效
VSCode 中配置 launch.json 启动调试
项目根目录下建 .vscode/launch.json，内容不是通用模板，得按实际运行方式选：
- 如果用 PHP 内置服务器（
php -S localhost:8000）：选Listen for Xdebug模式，VSCode 被动等连接 - 如果用 Apache/Nginx：选
Launch Built-in Web Server或Launch External Console，但更推荐前者，避免权限和路径问题 - 关键字段别写死：
"port"必须和xdebug.client_port一致（默认 9003）；"pathMappings"是必须项，把本地项目路径映射到服务器上 PHP 实际看到的路径（比如你本地开的是/Users/me/project，但 Apache DocumentRoot 是/var/www/html，就得写"pathMappings": { "/var/www/html": "${workspaceFolder}" }） - 示例（内置服务器 + 断点触发）：
{ "version": "0.2.0", "configurations": [ { "name": "Listen for Xdebug", "type": "php", "request": "launch", "port": 9003, "pathMappings": { "${workspaceFolder}": "${workspaceFolder}" } } ] }
启动调试前必做的三件事
很多人卡在这一步：断点灰色、控制台无响应、Xdebug 日志显示 “connection refused”。原因往往不是配置错，而是漏了下面这些：
- 关掉其他占用 9003 端口的进程（如旧版 PhpStorm、另一个 VSCode 窗口、Docker 容器）：用
lsof -i :9003（macOS/Linux）或netstat -ano | findstr :9003（Windows）查杀 - 浏览器装 Xdebug Helper 插件（Chrome/Firefox），并点击图标设为 “Debug”，否则 Xdebug 不会主动连 VSCode
- 确保 PHP 脚本里有明确断点（在代码行号左侧红点），且该脚本正被访问（比如你在
index.php打断点，就访问http://localhost:8000/index.php，而不是只运行php index.php）
复杂点在于：Xdebug 配置、VSCode 调试器、Web 服务器三者路径映射稍有不一致，断点就永远灰着；而日志（xdebug.log）默认不开启，得手动加 xdebug.log=/tmp/xdebug.log 才能定位连接失败的真实原因。
