Laravel+Vue.js应用PhpStorm Xdebug调试异常：API调用不触发断点

核心问题分析 #

前端发起的跨域请求未携带XDEBUG_SESSION=PHPSTORM Cookie，导致Xdebug无法识别调试会话，请求被Valet的入口文件拦截，无法进入Laravel业务代码断点。

解决方案 #

1. 给前端请求注入Xdebug会话标识 #

因为前端和后端是独立应用，浏览器不会自动传递调试Cookie，需手动添加：

• 方法一：浏览器插件临时设置
  用EditThisCookie这类插件，给后端域名（如your-api.test）添加Cookie：XDEBUG_SESSION=PHPSTORM，路径设为/，域名设为.your-api.test（支持子域名跨域）。
• 方法二：前端请求拦截器自动携带
  在Vue的axios请求拦截器中添加Cookie，确保跨域请求携带凭证：

  import axios from 'axios';
  
  axios.interceptors.request.use(config => {
    // 允许携带跨域凭证
    config.withCredentials = true;
    // 写入Xdebug会话Cookie（适配SSL环境）
    document.cookie = 'XDEBUG_SESSION=PHPSTORM; path=/; domain=.your-local-domain.test; secure';
    return config;
  });
  

  注意替换.your-local-domain.test为你的Valet站点根域名（如.myapp.test）。

2. 调整Xdebug配置强制启动调试 #

修改PHP的Xdebug配置文件（如/etc/php/8.2/cli/conf.d/20-xdebug.ini），强制每个请求启动调试，无需依赖Cookie：

xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=localhost
xdebug.client_port=9003
xdebug.discover_client_host=1
xdebug.log=/tmp/xdebug.log # 可选，用于排查连接问题

修改后重启Valet：valet restart

3. 修正PhpStorm服务器映射配置 #

• 打开PhpStorm的Settings > Build, Execution, Deployment > Servers
• 确保后端站点的配置中：
  • Name填写Valet域名（如your-api.test）
  • Host填写your-api.test
  • Port设为443，勾选Use SSL
  • Absolute path on server填写Laravel项目的根目录（如/home/ahmed/Sites/your-laravel-api），而非Valet的vendor路径
• 开启PhpStorm的调试监听：点击右上角的「电话」图标，确保显示「Listening for PHP Debug Connections」

4. 确保Valet站点路由正确 #

• 确认Laravel项目已通过valet link或valet park关联到Valet，且已启用SSL：valet secure your-api.test
• 检查项目的public目录是Valet的站点根目录，若结构异常，可手动指定：valet link --public public

5. 临时触发调试会话 #

如果以上配置仍有问题，可在API请求URL后追加调试参数强制触发：

https://your-api.test/api/endpoint?XDEBUG_SESSION_START=PHPSTORM

内容的提问来源于stack exchange，提问作者Ahmed Bermawy