vscode调试laravel成功取决于三件事：xdebug在cli和web模式均生效、launch.json的pathmappings精确匹配运行时路径、vscode终端能直接调用php和artisan；其他均为细节。
VSCode 本身不运行 Laravel，调试能否成功，只取决于三件事：Xdebug 是否在 CLI 和 Web 模式下都生效、launch.json 的 pathMappings 是否精确对应运行时路径、VSCode 终端能否直接调用 php 和 artisan。其他都是细节。
确保 php 和 artisan 在 VSCode 终端里能直接执行
很多调试失败，其实卡在第一步：终端根本找不到 PHP。VSCode 启动方式（比如从 Dock 或开始菜单点击）不会加载 shell 的 PATH，所以即使你在终端里 which php 能看到路径，VSCode 内置终端也可能报 command not found。
- 在系统终端运行
which php（macOS/Linux）或where php（Windows），拿到完整路径，例如/opt/homebrew/bin/php - 在项目根目录的
.vscode/settings.json中写死："php.validate.executablePath": "/opt/homebrew/bin/php" - 验证：打开 VSCode 终端，执行
php --version和php artisan list，两者都必须有正常输出
让 Xdebug 在 CLI 场景下也触发调试
Laravel 的 queue:work、schedule:run、事件监听器这些关键逻辑都在 CLI 下运行。如果 xdebug.start_with_request 没设对，断点永远不命中。
- 在
php.ini中统一配置（不是php-fpm.conf或单独的cli/php.ini）：xdebug.mode=debug、xdebug.start_with_request=yes、xdebug.client_host=127.0.0.1、xdebug.client_port=9003 - 不要用
trigger模式——它要求手动加XDEBUG_SESSION_START=1参数，容易漏；yes才能让php artisan queue:work自动连上 VSCode - 改完后重启 PHP-FPM（或 Apache/Nginx），如果是
php -S，需关掉再重开
launch.json 的 pathMappings 必须匹配运行时路径
VSCode 不知道你的代码在 PHP 进程里“叫什么名字”。如果 pathMappings 错了，断点会灰掉，变量显示为 undefined。
- Web 请求（如
php artisan serve）：PHP 进程工作路径通常是项目根目录，映射写成"/var/www/html": "${workspaceFolder}"是错的——除非你真在 Docker 里跑且容器内路径是那样 - 本地开发最安全的写法：
"pathMappings": { "${workspaceFolder}": "${workspaceFolder}" }，简单粗暴，避免路径拼错 - 如果用 Docker，必须填容器内的绝对路径，比如
"/var/www/app": "${workspaceFolder}"，不能猜
不同场景要区分断点位置和启动方式
不是所有断点都能在所有上下文生效。Laravel 的执行入口差异很大，硬塞断点没用。
- 调试 HTTP 接口：用
Listen for XDebug配置，浏览器访问或用REST Client发请求，断点打在控制器方法里 - 调试队列任务：确保
xdebug.start_with_request=yes已启用，在任务类的handle()方法开头设断点，然后终端执行php artisan queue:work - 调试 Artisan 命令：需要额外加一个
Launch currently open script配置，program指向artisan文件，并传参args，否则断点无效
最容易被忽略的是：Xdebug 的 CLI 配置和 Web 配置常被分开管理，而 Laravel 队列、调度、事件这些核心功能全依赖 CLI 模式下的 Xdebug 生效。很多人只配了 FPM，却忘了 CLI ini 文件可能完全没动过。
