VSCode 本身不内置 PHP 运行环境，需系统已安装 PHP 并配置 PATH；通过 php -S 启动内置服务器，配合 PHP Debug 和 Xdebug 实现调试，关键在于路径、版本匹配与环境变量生效。
VSCode 本身不内置 PHP 运行环境，也不能直接“启动 PHP 服务器”——它只是编辑器。真正运行 PHP 的是系统里已安装的 php 可执行文件，而本地服务器通常靠 php -S 内置服务器或配合 XAMPP/MAMP 等工具实现。配置的关键是让 VSCode 正确识别、调用并调试 PHP，而不是“装个插件就跑起来”。
确认系统已安装 PHP 并加入 PATH
这是所有后续操作的前提。VSCode 所有 PHP 相关功能（语法检查、格式化、调试、终端运行）都依赖命令行能直接调用 php。
- 在终端运行
php -v，必须返回版本号（如PHP 8.2.12），否则插件会报错或失效 - 如果提示
command not found或'php' is not recognized，说明 PHP 没装或没加到系统环境变量 PATH 中 - Windows 用户常见路径：
C:\php或 XAMPP 的C:\xampp\php；macOS 用 Homebrew 安装后一般自动加入 PATH；Linux 用户注意是否用了php8.2这类带版本号的命令别名 - 修改 PATH 后，务必重启 VSCode（不只是窗口，要彻底退出再打开），否则新环境变量不会生效
安装 PHP 插件并配置 php.executablePath
官方推荐插件是 PHP Intelephense（智能补全/跳转）和 PHP Debug（Xdebug 调试）。但即使只写代码，也必须告诉 VSCode php 命令在哪。
- 打开设置（
Ctrl+,或Cmd+,），搜索php.executablePath - 如果
php -v在终端可用，留空即可；否则需填绝对路径，例如：C:\php\php.exe（Windows）、/usr/local/bin/php（macOS）、/usr/bin/php（Ubuntu） - 不要填错成
php.ini路径或扩展目录——那是给 PHP 自己用的，不是给 VSCode 找可执行文件的 - Intelephense 的
intelephense.environment.includePaths是用来补全第三方库路径的，和运行无关，别混淆
用 php -S 快速启动本地开发服务器
PHP 5.4+ 自带轻量级 CLI 服务器，适合开发时快速预览，无需 Apache/Nginx。它只响应 HTTP 请求，不处理 .htaccess 或虚拟主机配置。
立即学习“PHP免费学习笔记（深入）”；
- 在项目根目录打开 VSCode 内置终端（
Ctrl+`），运行：php -S localhost:8000 -t public -
-t public表示将public/目录设为 Web 根（类似 Apache 的 DocumentRoot），没有该目录会报错 - 如果入口是
index.php在项目根目录，就用：php -S localhost:8000（默认找当前目录下的router.php或index.php） - 浏览器访问
http://localhost:8000即可；终端会实时打印请求日志，Ctrl+C 停止 - 注意：这个服务器不支持并发、静态资源缓存或 HTTPS，生产环境绝不能用
调试时确保 Xdebug 版本与 PHP 匹配
VSCode 的 PHP Debug 插件本质是连接 Xdebug，而 Xdebug 必须编译匹配当前 PHP 版本和 ZTS（线程安全）设置，否则 phpinfo() 里根本看不到 Xdebug 模块。
- 运行
php -v看 PHP 版本和 ZTS 状态（含with ZTS表示线程安全） - 去 xdebug.org/download 下载对应版本的
php_xdebug.dll（Windows）或xdebug.so（macOS/Linux） - 在
php.ini中添加（注意路径和分号注释）：zend_extension=/path/to/xdebug.so xdebug.mode=debug xdebug.client_host=127.0.0.1 xdebug.client_port=9003
- 重启 PHP（如果是 CLI 服务器，关掉再重开；如果是 Apache，需重启服务）
- 在 VSCode 中按
F5启动调试前，先确认左下角显示“PHP Debug”且端口是9003（Xdebug 3 默认端口，不是旧版的 9000）
最容易卡住的地方不是插件没装，而是 php 命令找不到、php.ini 改错了位置、Xdebug 扩展版本不匹配，或者调试时没在浏览器装 Xdebug Helper 插件并开启调试会话。每一步都要验证输出，别凭感觉往下走。
