VS Code 通过配置 tasks.json 启动 PHP 内置服务器并配合 PHP Debug 扩展实现调试；需确保 PHP CLI 正确安装并加入 PATH，配置 Xdebug 3 及 launch.json 的 pathMappings，且 router.php 需手动处理路由和路径映射。
VS Code 本身不自带 PHP 内置服务器，但可以轻松调用 php -S 启动它；关键不是“在 VS Code 里运行服务器”，而是让 VS Code 正确识别、启动并调试这个命令。
确认 PHP CLI 已正确安装且可被 VS Code 访问
很多“启动失败”其实卡在这一步：VS Code 的集成终端或任务系统找不到 php 命令。
- 在 VS Code 终端中直接运行
php -v，必须返回版本号；若报command not found，说明 PATH 未配置好（macOS/Linux 检查 shell 配置文件，Windows 检查系统环境变量） - 不要依赖 XAMPP/MAMP 的 PHP —— 它们通常不加入全局 PATH，且内置服务器功能可能被禁用（
--disable-phar会导致php -S不可用） - 推荐用 windows.php.net（Windows）或
brew install php（macOS）安装官方 CLI 版本
用 tasks.json 快速启动 PHP 内置服务器
手动敲 php -S localhost:8000 太重复，用 VS Code 的任务功能一键拉起更可靠。
- 项目根目录建
.vscode/tasks.json，内容如下：
{
"version": "2.0.0",
"tasks": [
{
"label": "Start PHP Server",
"type": "shell",
"command": "php -S localhost:8000 -t public",
"isBackground": true,
"problemMatcher": [],
"group": "build",
"presentation": {
"echo": true,
"reveal": "always",
"focus": false,
"panel": "shared",
"showReuseMessage": true,
"clear": false
}
}
]
}
-
-t public指定文档根目录（按 Laravel/Slim 等框架习惯），如项目无public/，改用-t . -
"isBackground": true是必须的，否则任务会立即退出；同时需配空problemMatcher，否则 VS Code 会等一个“任务完成信号”而卡住 - 按
Ctrl+Shift+P→ “Tasks: Run Task” → 选 “Start PHP Server”，终端即启动服务
配合 PHP Debug 扩展实现断点调试
仅启动服务器还不够，要进断点，必须让 PHP 调试器（Xdebug 或 OpenTelemetry）与 VS Code 连通。
立即学习“PHP免费学习笔记（深入）”；
- 先装官方扩展：PHP Debug（by Felix Becker），再确认 PHP.ini 中已启用并配置 Xdebug（以 Xdebug 3 为例）：
zend_extension=xdebug.so xdebug.mode=debug xdebug.start_with_request=yes xdebug.client_host=127.0.0.1 xdebug.client_port=9003
- 在 VS Code 中添加
.vscode/launch.json，启用“Listen for Xdebug”配置：
{
"version": "0.2.0",
"configurations": [
{
"name": "Listen for Xdebug",
"type": "php",
"request": "launch",
"port": 9003,
"pathMappings": {
"/var/www/html": "${workspaceFolder}"
}
}
]
}
-
pathMappings是关键：左边是服务器视角的绝对路径（比如php -S启动时工作目录的绝对路径），右边是本地项目路径；两者必须严格对应，否则断点不命中 - 启动调试前，确保 Xdebug 日志开启（
xdebug.log=/tmp/xdebug.log），遇到连不上时优先查日志里是否显示“Connection to IDE failed”
常见错误：浏览器访问 500 错误 / 404 / 白屏
这些不是 VS Code 的问题，而是 php -S 的路由机制和脚本执行环境导致的。
-
php -S默认只服务静态文件；PHP 脚本需要显式路由处理器（router script）。例如访问/user/123报 404，是因为没提供router.php - 加
-t public router.php后，在router.php中必须手动include对应脚本，且注意$_SERVER['SCRIPT_FILENAME']是真实磁盘路径，不是 URL 路径 - 500 错误常因
router.php中语法错误、未加载 Composer autoloader、或扩展缺失（如mbstring）；此时看终端里php -S输出的错误行，不是浏览器响应 - 白屏且无报错？检查
display_errors = On和error_reporting = E_ALL是否在 CLI 的 php.ini 中生效（CLI 和 Web SAPI 的配置文件可能不同）
真正麻烦的从来不是启动命令本身，而是 router.php 怎么写、Xdebug 的 pathMappings 怎么对齐、以及 CLI 和 Web 模式下 php.ini 的差异 —— 这三处出问题，调试就卡死在“看起来都对，但就是不动”。
