PhpStorm调试Homestead需配置CLI解释器指向Vagrant、严格设置路径映射、使用Xdebug3新参数（如xdebug.client_host=192.168.10.1、client_port=9003）、启用监听并手动加XDEBUG_SESSION_START参数。
CLI Interpreter 必须指向 Homestead 虚拟机
PhpStorm 默认用本地 PHP 解释器，但 Homestead 里跑的是虚拟机内的 PHP（比如 /usr/bin/php），不切换就根本执行不了 Laravel 命令、Artisan 或 Composer install。
操作路径：Preferences → Languages & Frameworks → PHP → CLI Interpreter，点击 + → 选 From Docker, Vagrant, VM, Remote... → 类型选 Vagrant → Vagrant Instance Folder 填你本地 Homestead 目录（如 ~/Homestead）。
- 成功标志是右侧出现
ssh://vagrant@127.0.0.1:2222并带绿色对勾 - 如果报 “Connection refused”，检查
vagrant status是否为running；若不是，先vagrant up - 别手动填 SSH 地址或端口——Vagrant 插件会自动读取
Vagrantfile里的配置，硬写容易错
路径映射（Path Mapping）错一个字符就断点失效
PhpStorm 在宿主机上设断点，但代码实际运行在虚拟机里。必须把本地项目路径和虚拟机内绝对路径严格对应，否则调试时找不到文件、跳转失败、变量不显示。
位置：Preferences → Languages & Frameworks → PHP → Servers，添加或编辑你的站点（如 homestead.test），勾选 Use path mappings，右侧填：
立即学习“PHP免费学习笔记（深入）”；
-
File/Directory：你本地项目的public或根目录（如/Users/you/code/myapp） -
Absolute path on the server：Homestead 中对应路径，**必须以/home/vagrant/code/xxx开头**（根据Homestead.yaml的folders和sites配置确定） - 常见错误：漏掉
/home/vagrant，写成/var/www（那是旧版或自定义镜像路径）；或本地路径用了相对路径
Xdebug3 的配置项名全变了，照搬旧教程必挂
Homestead v12+ 默认用 Xdebug3（PHP 8.0+ 环境基本都是），xdebug.remote_* 全部废弃，换成 xdebug.client_* 和 xdebug.mode。
编辑虚拟机内配置（如 PHP 8.1）：sudo vim /etc/php/8.1/fpm/conf.d/20-xdebug.ini，关键项必须这样写：
zend_extension=xdebug.so xdebug.mode=debug xdebug.start_with_request=yes xdebug.client_host=192.168.10.1 xdebug.client_port=9003 xdebug.idekey=PHPSTORM xdebug.max_nesting_level=512
-
client_host填宿主机 IP（不是localhost），Homestead 默认网段是192.168.10.0/24，宿主机即192.168.10.1 -
client_port要和 PhpStorm 里Preferences → PHP → Debug → DBGp Proxy → Port一致，默认是9003（Xdebug2 是9000，混用会连不上） - 改完必须重启 PHP-FPM：
sudo service php8.1-fpm restart，光 reload 不生效
启动监听前先确认 xdebug.log 有没有连接记录
断点不触发？请求没进 PhpStorm？别急着重配，先看日志——这是最直接的证据。
在 20-xdebug.ini 加一行：xdebug.log=/tmp/xdebug.log，然后访问一次页面，再进虚拟机执行：
vagrant ssh -c "tail -20 /tmp/xdebug.log"
正常会有类似 [Step Debug] INFO: Connecting to configured address: 192.168.10.1:9003 的记录；如果出现 Connection refused 或空输出，说明要么 PhpStorm 没监听，要么端口/地址不匹配。
- PhpStorm 启动监听：菜单栏
Run → Start Listening for PHP Debug Connections（按钮亮起才生效） - 浏览器访问时加参数：
?XDEBUG_SESSION_START=PHPSTORM（注意值要和xdebug.idekey完全一致，大小写敏感） - 别依赖浏览器插件自动触发——它可能被禁用、或没识别当前域名，手动加参最稳
路径映射和 Xdebug3 参数是两个最高频的故障点，调不通时优先盯死这两处，其他环节基本是连带结果。
