PhpStorm连上Vagrant不等于能运行、调试或同步，核心卡点是同步方式、PHP解释器路径及Xdebug网络指向未对齐：需手动配置Vagrant可执行路径与实例目录，PHP路径填虚拟机内绝对路径（如/usr/bin/php），xdebug.client_host设为10.0.2.2，路径映射严格匹配DocumentRoot。
PhpStorm 能连上 Vagrant 不代表代码能跑、断点能停、文件修改能实时生效——核心卡点在同步方式、PHP 解释器路径、Xdebug 网络指向三者没对齐。
PhpStorm 识别不到 Vagrantfile 或 Vagrant 菜单全灰
这不是项目结构问题，是 PhpStorm 根本没找到 Vagrant 可执行文件，也没被告知该去哪读 Vagrantfile。
- 终端运行
vagrant --version必须有输出；没有就重装或检查 PATH -
Settings → Tools → Vagrant中Vagrant executable填绝对路径：/usr/local/bin/vagrant（macOS/Linux）或C:\HashiCorp\Vagrant\bin\vagrant.exe（Windows） -
Vagrant instance folder必须指向含Vagrantfile的目录——不是项目根目录，也不是子目录；例如你执行cd /home/user/myapp && vagrant up，那这里就是/home/user/myapp - WSL2 + Windows PhpStorm 场景下，不能填
/home/user/myapp，得用\wsl$\Ubuntu\home\user\myapp这类 Windows 映射路径
PHP CLI 解释器始终指向宿主机而非 Vagrant 内 PHP
PhpStorm 默认只查本地 PATH，不会自动执行 vagrant ssh -c "which php"。手动填错路径或信“自动探测”，90% 失败。
- 先确认虚拟机已运行：
vagrant status显示running - 执行
vagrant ssh -c "which php"查真实路径，结果通常是/usr/bin/php或/opt/php8.1/bin/php -
Settings → Languages & Frameworks → PHP → CLI Interpreter → Add → Remote Interpreter → Vagrant，确保Vagrant instance folder和前面一致 - 手动切到
SSH Configuration页签：Host填127.0.0.1（不是localhost），Port填vagrant ssh-config输出的Port值（如2222） -
Private key file点右侧按钮选vagrant ssh-config输出的IdentityFile（如.vagrant/machines/default/virtualbox/private_key） -
PHP executable path必须填绝对路径，php或php8.1这类 alias 不生效
Vagrant 同步文件夹不生效或修改后不自动更新
默认的 VirtualBox 共享文件夹性能差、权限怪、监听失效；NFS/rsync 才是实际开发中可依赖的方式。
立即学习“PHP免费学习笔记（深入）”；
- 若用 NFS：
config.vm.synced_folder ".", "/var/www/html", type: "nfs"，宿主机需已安装nfs-client（Ubuntu/Debian：sudo apt install nfs-kernel-server） - 若用 rsync（推荐）：
config.vm.synced_folder ".", "/var/www/html", type: "rsync"，修改后需手动触发vagrant rsync，或加rsync__auto: true启用后台监听（但部分系统不兼容） - 别依赖
vagrant reload自动同步——它只重载配置，不刷新文件内容 - Web 服务器 DocumentRoot（如 Nginx 的
root /var/www/html）必须和 synced_folder 目标路径严格一致，否则 403/404
Xdebug 断点不触发但 PhpStorm 显示“已连接”
这是典型的“假连通”：SSH 通了、端口映射开了、扩展加载了，但 xdebug.client_host 指向错误网关，Xdebug 尝试连一个不存在的地址。
- VirtualBox 默认网关是
10.0.2.2，php.ini中必须设xdebug.client_host=10.0.2.2（不是127.0.0.1） -
xdebug.mode=debug（Xdebug 3）且xdebug.start_with_request=yes或通过 URL 参数?XDEBUG_SESSION_START=PHPSTORM触发 - 确保
config.vm.network "forwarded_port", guest: 9003, host: 9003已配置（Xdebug 3 默认端口） - PhpStorm 的 Debug 监听地址必须是
127.0.0.1:9003，且绿色小虫图标已点亮（表示正在监听） - 路径映射（Path Mapping）必须精确匹配：本地
/path/to/project→ 远程/var/www/html，漏一级目录就找不到源码
最常被忽略的是路径映射与 Web 服务器 DocumentRoot 的一致性，以及 xdebug.client_host 和 VirtualBox 网络模式的绑定关系——换用 VMware 或 Docker Desktop 时，这个 IP 就不是 10.0.2.2 了。
