PhpStorm 连不上 Vagrant 主因是 vagrant ssh-config 的 HostName、Port、IdentityFile 填错；需验证 IdentityFile 存在且权限为600、路径无中文空格；Windows+WSL2 须用 Windows 映射路径；Remote PHP 解释器路径须手动指定绝对路径；Xdebug 需设 client_host 为虚拟机网关（如10.0.2.2），端口与 PhpStorm 一致；路径映射必须严格一一对应，否则断点失效。
PhpStorm 连不上 Vagrant，90% 是因为没填对 vagrant ssh-config 里那几行关键字段，而不是 SSH 密钥或网络不通。
确认 vagrant ssh-config 输出是否可用
这是所有配置的起点。别跳过这步，也别靠记忆或截图里的旧值。
- 在含
Vagrantfile的目录下运行vagrant ssh-config - 重点看三行：
HostName（通常是127.0.0.1）、Port（比如2222或2200）、IdentityFile（路径如.vagrant/machines/default/virtualbox/private_key） - 检查
IdentityFile文件是否存在、权限是600、路径不含中文或空格；否则 PhpStorm 会静默失败 - Windows 下若用 WSL2，
IdentityFile路径必须用 Windows 映射格式（如\wsl$\Ubuntu\home\user\project\.vagrant\...），不能填 Linux 路径
PhpStorm 中配置 Remote PHP 解释器为 Vagrant
它不会自动识别虚拟机里的 php，也不会查 PATH —— 必须手动指定绝对路径。
- Settings → Languages & Frameworks → PHP → CLI Interpreter → Add → Remote Interpreter → Vagrant
-
Vagrant instance folder必须指向含Vagrantfile的目录（不是子项目目录，也不是src/） - 解释器路径填
/usr/bin/php或/usr/local/bin/php；不确定就先vagrant ssh -c "which php"查实 - 如果用 Homestead 或自定义 box，可能是
/opt/php8.2/bin/php或/usr/bin/php-fpm；CLI 和 FPM 配置不同，别混用 - 别勾选 “Use path mappings for CLI interpreter”，除非你明确需要命令行脚本也走远程映射逻辑
调试时 Xdebug 断点不触发？先查 xdebug.client_host
不是 PhpStorm 没监听，也不是 Xdebug 没装，而是反向连接地址错了。
立即学习“PHP免费学习笔记（深入）”；
- Vagrant 内执行
ip route | awk '/default/ {print $3}'，通常输出10.0.2.2（VirtualBox 默认网关） - 对应 PHP 版本的
php.ini（CLI 和 FPM 分开查！）里设：xdebug.client_host = 10.0.2.2 - Xdebug 3 还要确认：
xdebug.start_with_request = trigger或yes，不能只靠浏览器插件开关 - PHPStorm 的 Debug 端口（Settings → PHP → Debug → Xdebug → Debug port）必须和
xdebug.client_port（默认9003）一致 - 确保
Run → Start Listening for PHP Debug Connections已点击（小虫子图标亮起）
路径映射（Path Mapping）错一位，断点就永远找不到源码
这是最隐蔽也最容易被忽略的一环：本地路径和虚拟机内路径必须严格一一对应。
- Settings → PHP → Servers → 编辑你的 Server → Path Mapping
- 左侧（“Absolute path on the server”）填虚拟机内项目真实路径，例如：
/var/www/myapp（不是/vagrant，除非你明确把项目放在那里） - 右侧（“Project files”）填宿主机本地项目根路径，例如：
/Users/me/myapp（Mac/Linux）或C:\dev\myapp（Windows） - 如果用的是 NFS 或 rsync 同步，路径必须和同步目标一致；默认
vboxsf共享可能有延迟或权限问题，建议改用rsync方式 - 错误提示 “Debug session was finished without being paused” 几乎全是这里配错导致的
真正卡住人的地方，往往不是某一步没做，而是多个环节的细节叠加失效：比如 vagrant ssh-config 的端口填对了，但 IdentityFile 权限不对；解释器路径写对了，但路径映射少了一个 /；Xdebug 配置全对，但 PhpStorm 没点那个小虫子图标。每一步都要验证，别假设它“应该可以”。
