xdebug 是 laravel 本地开发中最常用、最可靠的 php 断点调试工具，需确保 php 版本兼容、php.ini 正确配置（xdebug.mode=debug、client_host/port、start_with_request=yes）、ide（phpstorm/vs code）监听启用且路径映射准确，并针对 artisan 命令或 api 请求手动触发调试。
在 Laravel 本地开发中，Xdebug 是最常用、最可靠的 PHP 断点调试工具。要让它真正跑起来，不能只装扩展，关键得让 PHP、IDE（如 PHPStorm 或 VS Code）和 Laravel 应用三者对齐配置。下面按实际调试流程梳理核心步骤和常见卡点。
确认 Xdebug 已正确加载并匹配 PHP 版本
Xdebug 必须与当前 PHP 版本（包括线程安全 TS/NTS、架构 x64/x86）完全匹配，否则 php -v 或 phpinfo() 中不会显示 Xdebug 模块。
- 运行
php -v查看 PHP 版本及编译信息（注意 “Thread Safety” 和 “Architecture”） - 去 xdebug.org/download 下载对应版本的
php_xdebug.dll（Windows）或xdebug.so（macOS/Linux） - 将扩展文件放入
ext/目录，并在php.ini中添加：zend_extension=xdebug<br>xdebug.mode=debug<br>xdebug.start_with_request=yes<br>xdebug.client_host=127.0.0.1<br>xdebug.client_port=9003
- 重启 Web 服务（如 Apache/Nginx）或 PHP-FPM，再执行
php --ini确认生效的 php.ini 路径，然后php -m | grep xdebug验证加载成功
PHPStorm：一键启动监听 + 正确设置路径映射
PHPStorm 对 Xdebug 支持最成熟，但路径映射（Path Mapping）配错会导致断点“灰掉”——这是本地调试失败的最常见原因。
- 打开 Run → Start Listening for PHP Debug Connections（确保右下角出现 “Debug listening…” 提示）
- 进入 Preferences → Languages & Frameworks → PHP → Servers，添加本地服务器（如
localhost），勾选 “Use path mappings” - 在映射表中，左侧填项目在浏览器访问时的根 URL 路径（如
http://localhost:8000），右侧填你本地 Laravel 项目的绝对路径（如/Users/you/code/my-laravel） - 确保
public/index.php是入口，且断点打在控制器、模型等可执行逻辑行上（不要打在注释或空行）
VS Code：精简配置 + 浏览器插件联动
VS Code 更轻量，适合快速调试，依赖 PHP Debug 扩展（由 xdebug作者维护）和浏览器辅助触发。
- 安装扩展 PHP Debug（必须是 “Felix Becker” 发布的官方版）
- 在项目根目录创建
.vscode/launch.json，内容如下：{<br> "version": "0.2.0",<br> "configurations": [<br> {<br> "name": "Listen for Xdebug",<br> "type": "php",<br> "request": "launch",<br> "port": 9003,<br> "pathMappings": {<br> "/var/www/html": "${workspaceFolder}"<br> },<br> "hostname": "127.0.0.1"<br> }<br> ]<br>} - 若用 Laravel Valet / Sail / Docker，需根据实际容器路径调整
pathMappings（例如 Sail 中 PHP 容器内路径通常是/var/www/html） - 安装浏览器插件 Xdebug Helper（Chrome/Firefox），右键图标选择 “Debug”，再刷新页面即可触发断点
Laravel 特殊场景处理：Artisan 命令与 API 请求
Web 请求调试通了，不代表 Artisan 命令或 Postman 调用 API 就能自动断点——它们默认不带 Xdebug 触发头，需手动介入。
- 调试 Artisan 命令：终端执行前加环境变量，例如：
XDEBUG_MODE=debug php artisan make:controller TestController - 调试 API 接口（如 Postman）：在请求 Headers 中添加
XDEBUG_SESSION_START=PHPSTORM（值需与 IDE 设置的 Key 一致，默认是 PHPSTORM） - 若用 Laravel Sail，先运行
./vendor/bin/sail up，再在另一终端执行带 XDEBUG_MODE 的命令；同时确保sail debug已启用或容器端口 9003 已暴露 - 检查
APP_DEBUG=true和APP_ENV=local，避免 Laravel 错误页拦截调试流
