Laravel Sail 中使用 Xdebug 调试 API 请求的完整指南-php教程-PHP中文网

Laravel Sail 中使用 Xdebug 调试 API 请求的完整指南

在 Laravel Sail 环境中调试 API 时，Xdebug 默认仅响应浏览器 Cookie 触发（如 XDEBUG_SESSION=PHPSTORM），而 Postman 或 curl 等工具不会自动携带该 Cookie，导致断点不生效；本文详解两种可靠解决方案：手动注入调试会话 Cookie 或配置 Xdebug 自动启动。

在 laravel sail 环境中调试 api 时，xdebug 默认仅响应浏览器 cookie 触发（如 `xdebug_session=phpstorm`），而 postman 或 curl 等工具不会自动携带该 cookie，导致断点不生效；本文详解两种可靠解决方案：手动注入调试会话 cookie 或配置 xdebug 自动启动。

Laravel Sail 内置的 Xdebug 配置默认采用 xdebug.start_with_request = trigger 模式，即仅当请求中包含有效的 XDEBUG_SESSION Cookie（如 XDEBUG_SESSION=PHPSTORM）时才启动调试会话。这在浏览器中可通过 Xdebug Helper 插件自动注入，但对 Postman、curl、HTTPie 或前端 AJAX 请求等 API 调用方式无效——因为它们默认不发送该 Cookie。

✅ 方案一：手动添加 XDEBUG_SESSION Cookie（推荐用于按需调试）

这是最灵活、最安全的方式，无需修改全局配置，适用于临时调试特定接口：

Postman：在请求的 Headers 标签页中，点击 Add → 输入 Key Cookie，Value 为 XDEBUG_SESSION=PHPSTORM（值可自定义，如 sail，但需与 IDE 的 Xdebug 配置一致）；

curl 示例：

curl -X POST "http://localhost:8000/api/users" \
  -H "Content-Type: application/json" \
  -H "Cookie: XDEBUG_SESSION=PHPSTORM" \
  -d '{"name":"John","email":"john@example.com"}'

注意事项：确保你的 IDE（如 PHPStorm、VS Code + PHP Debug 扩展）已启用 Xdebug 监听，并监听端口 9003（Laravel Sail 默认配置）；同时确认 .env 中 SAIL_XDEBUG_MODE=debug,develop 已启用。

✅ 方案二：强制 Xdebug 对所有请求启动（适合开发环境）

修改 Xdebug 启动策略，使其无需 Cookie 即可触发：

进入 Sail 容器并定位 Xdebug 配置文件：
```
sail artisan tinker
# 在 Tinker 中执行：
>>> echo xdebug_info();
```
查看输出中的 Loaded Configuration File 路径（通常为 /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini）。
编辑该文件（宿主机上）：

Laravel Creem Agent
Creem 支付商店助理 — 查询订阅、客户、交易、产品，执行心跳检查，管理本地 Laravel支付商店。

下载
```
# 在项目根目录执行
nano docker-compose.yml
```
找到 laravel.test 服务的 volumes 部分，确保挂载了自定义 Xdebug 配置（或直接编辑容器内文件）：
```
volumes:
  - '.:/var/www/html'
  - './docker/php/xdebug.ini:/usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini'
```

创建 docker/php/xdebug.ini，覆盖关键配置：

zend_extension=xdebug.so
xdebug.mode=debug,develop
xdebug.client_host=host.docker.internal
xdebug.client_port=9003
xdebug.start_with_request=yes   ; ← 关键：改为 yes，而非 trigger
xdebug.log=/var/log/xdebug.log

? 提示：xdebug.start_with_request=yes 表示每个 HTTP/CLI 请求均启动调试会话；生产环境严禁使用，仅限本地开发。

重启 Sail 容器使配置生效：
```
sail down && sail up -d
```

⚠️ 注意事项与最佳实践

安全性：start_with_request=yes 会显著增加请求开销，且暴露调试端口风险，切勿在共享或预发布环境中启用；
IDE 配置同步：确保 IDE 的 Xdebug 设置中 Debug port 为 9003，Filter 中勾选 Listen for incoming connections；
验证是否生效：在控制器中插入 xdebug_break() 或设置断点后，用 phpinfo() 或 xdebug_info() 检查当前模式与连接状态；
多环境区分：建议通过 .env.sail 或条件化 Docker Compose 配置实现开发/测试环境的 Xdebug 策略隔离。

通过以上任一方式，你即可在 Postman、Insomnia、cURL 或前端应用中稳定触发 Xdebug 断点，真正实现 Laravel API 的全链路可视化调试。