VS Code 运行 PHP 需三步：本地安装 PHP CLI 并配置系统 PATH；在设置中指定 php.executablePath 绝对路径；安装 PHP Intelephense 和 PHP Debug 扩展，再正确配置 Xdebug。

VS Code 本身不内置 PHP 运行环境，它只是编辑器；真正要让 PHP 文件能运行、调试、语法校验，关键在三件事：本地装好 PHP CLI、配置好 php.executablePath、再按需装扩展（如 PHP Intelephense 或 PHP Debug）。没装 PHP 解释器，装再多插件也跑不起来。

确认系统已安装 PHP CLI 并可用

这是最常被跳过的一步。很多人只下载了 XAMPP/WAMP/MAMP，但没把 php.exe（Windows）或 php（macOS/Linux）加进系统 PATH，导致 VS Code 找不到命令。

• 终端里直接运行 php -v，必须返回版本号（如 PHP 8.2.12），否则 VS Code 的任何 PHP 功能都会报错 “Command 'php' not found”
• Windows 用户常见路径：C:\xampp\php\php.exe、C:\wamp64\bin\php\php8.2.12\php.exe；macOS 用 Homebrew 安装的通常在 /opt/homebrew/bin/php
• 如果没装，别急着开 VS Code —— 先去 windows.php.net 下 ZIP 包解压，或用 brew install php（macOS），再手动配 PATH

在 VS Code 中指定 php.executablePath

即使 php -v 在终端能用，VS Code 的某些功能（比如格式化、IntelliSense 启动时的解析）仍可能因环境变量隔离而找不到 PHP。显式配置路径最稳妥。

• 打开 VS Code 设置（Ctrl+, 或 Cmd+,），搜 php executable path
• 找到 PHP > Executable Path 项，填入绝对路径，例如：C:\xampp\php\php.exe 或 /opt/homebrew/bin/php
• 改完不用重启，但建议关掉所有 PHP 文件再重开，避免缓存旧配置
• 注意：路径里不能有中文、空格（若必须，用双引号包裹，但不推荐；优先改路径）

装对扩展，别全堆上

VS Code 市场里 PHP 相关扩展几十个，但日常开发真正核心就两个，装错或装多反而冲突：

• PHP Intelephense：提供代码补全、跳转、类型推断、错误提示 —— 替代原生 PHP Language Basics，更准更快
• PHP Debug（由 xdebug-php 团队维护）：配合 Xdebug 实现断点调试；注意它不自带 Xdebug，得自己配 php.ini
• 别装 “PHP Extension Pack” 这类合集包 —— 它常捆绑过时或冗余扩展（如老版 PHP Debug），容易和你手动装的冲突
• 如果用 Laravel，可额外加 Laravel Blade Snippets；纯原生 PHP 开发，这两个足矣

调试前必须检查 Xdebug 配置是否生效

装了 PHP Debug 扩展 ≠ 能调试。Xdebug 必须正确加载且监听端口，否则点击“开始调试”只会卡住或报 Connection refused。

• 在终端运行 php -m | findstr xdebug（Windows）或 php -m | grep xdebug（macOS/Linux），确保输出含 xdebug
• 检查 php.ini 中是否启用：必须有 zend_extension=xdebug 行（路径要对），且 xdebug.mode=debug、xdebug.start_with_request=yes（PHP 8.0+）或 xdebug.remote_enable=1（旧版）
• VS Code 的 launch.json 里 port 要和 xdebug.client_port 一致（默认 9003）；PHP 8.0+ 默认用 9003，别还写 9000
• 浏览器装 Xdebug Helper 插件（Chrome/Firefox），并设为 “Debug”，才能触发调试会话

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

最难的不是配步骤，而是判断哪一层断了：是 PHP 没装？PATH 没生效？xdebug.so 没加载？还是 port 写错了？每次失败，先回到终端跑 php -v 和 php --ini，确认解释器和配置文件位置，比瞎改 launch.json 有用得多。