VS Code 调试 PHP 依赖 xdebug 正确配置：需确认 php -v 含 xdebug ≥3.0、php.ini 启用 zend_extension 及 xdebug.mode=debug 等参数、安装 felixfbecker 的 PHP Debug 插件、配置 launch.json 的 pathMappings 与实际路径一致，并通过 ?XDEBUG_SESSION=1 或 XDEBUG_MODE=debug 触发调试。
VS Code 本身不直接执行 PHP，调试依赖 xdebug 或 zend-debugger（主流是 xdebug），所以“能设断点”不等于“点一下就能停住”——关键在 PHP 运行时是否真的把调试信息发给了 VS Code。
确认 PHP 环境已加载 xdebug 并处于调试模式
很多断点不命中，根本原因不是 VS Code 配置错，而是 phpinfo() 里压根没看到 xdebug 模块，或它处于 off 状态。
- 运行
php -v，输出中必须包含xdebug字样且版本号 ≥ 3.0（推荐 3.3+） - 运行
php --ini找到Loaded Configuration File路径，打开该php.ini - 检查是否有类似以下配置（注意：xdebug 3 和 2 的配置项完全不同）：
zend_extension=xdebug xdebug.mode=debug xdebug.start_with_request=trigger xdebug.client_host=127.0.0.1 xdebug.client_port=9003
⚠️ 常见坑：xdebug.mode=off（默认值）、client_port 写成 9000（xdebug 3 默认是 9003，而 VS Code 默认监听 9003；若改了端口，VS Code 的 launch.json 也得同步改）
安装并启用 PHP Debug 插件（felixfbecker 插件）
VS Code 官方市场里搜 PHP Debug，认准作者是 felixfbecker（GitHub 仓库名 felixfbecker/vscode-php-debug），这是唯一被 xdebug 官方文档推荐的调试器。
立即学习“PHP免费学习笔记（深入）”；
- 安装后重启 VS Code（插件需激活）
- 确保没有同时启用其他 PHP 调试类插件（如旧版
PHP Tools的调试功能），会端口冲突 - 插件启用后，状态栏右下角会出现
PHP Debug字样（悬停可看 xdebug 版本）
配置 .vscode/launch.json 启动调试会话
项目根目录下建 .vscode/launch.json，内容不是通用模板，要匹配你的运行方式（CLI 还是 Web）。
- 如果是命令行脚本（如
php index.php）：
{
"version": "0.2.0",
"configurations": [
{
"name": "Listen for Xdebug",
"type": "php",
"request": "launch",
"port": 9003,
"pathMappings": {
"/var/www/html": "${workspaceFolder}"
}
}
]
}
- 如果是 Web 请求（浏览器访问
http://localhost/index.php）：
{
"version": "0.2.0",
"configurations": [
{
"name": "Listen for Xdebug",
"type": "php",
"request": "launch",
"port": 9003,
"pathMappings": {
"/var/www/html": "${workspaceFolder}"
},
"hostname": "localhost",
"url": "http://localhost/index.php"
}
]
}
重点看 pathMappings：左边是 PHP 进程里文件的绝对路径（echo __FILE__ 看到的），右边是本地项目路径。Windows 用户注意用正斜杠或双反斜杠，例如 "C:/myproject"，不能写 "C:\myproject"（JSON 解析失败）。
触发断点的两种可靠方式
设好断点后，VS Code 不会自动监听所有请求——你得明确告诉 xdebug：“这次请求我要调试”。
- Web 场景：在 URL 后加
?XDEBUG_SESSION_START=1（xdebug 3 默认 session key 是XDEBUG_SESSION，值任意非空，如?XDEBUG_SESSION=1） - CLI 场景：命令前加环境变量，例如
XDEBUG_MODE=debug php index.php - 更省事：浏览器装
Xdebug Helper插件（Chrome/Firefox），点击图标开启调试，它会自动在请求头或 Cookie 中注入调试标识
断点生效的前提是：xdebug 已连接上 VS Code（状态栏出现 “Xdebug listening” 提示），且请求路径和 pathMappings 完全对得上——哪怕多一个 / 都可能找不到文件。
