在Vagrant虚拟机环境配置Xdebug远程调试的详细指南-php教程-PHP中文网

xdebug在vagrant中远程调试失败主因是xdebug.remote_host配置错误、cli与fpm配置未分离、phpstorm未监听端口；需分别验证两sapi加载xdebug、确认各自ini路径、设对宿主机ip、phpstorm正确配置远程解释器/路径映射/启动监听，并为cli脚本注入xdebug_config环境变量。

在vagrant虚拟机环境配置xdebug远程调试的详细指南

Xdebug 在 Vagrant 中远程调试失败，90% 是因为 xdebug.remote_host 填错了、CLI 和 FPM 配置没分开、或 PHPStorm 没监听端口。

确认 Xdebug 是否真正加载到 CLI 和 FPM 两个 SAPI

很多人只改了 /etc/php/7.4/fpm/conf.d/xdebug.ini，却忘了 CLI 调试（比如 drush、artisan）走的是另一套配置。不一致就会出现「网页能断点，命令行死活连不上」。

在 Vagrant 内分别执行：php -v（看 CLI）、php-fpm -t（看 FPM），再各自跑 php -m | grep xdebug 和 php-fpm -m | grep xdebug —— 必须都输出 xdebug
检查加载路径：php --ini 和 php-fpm -i | grep "Loaded Configuration File"，确认两个环境读的是不同 ini 文件（常见路径：CLI 用 /etc/php/7.4/cli/conf.d/20-xdebug.ini，FPM 用 /etc/php/7.4/fpm/conf.d/20-xdebug.ini）
如果只在一个里生效，就复制一份配置过去，别指望「共用一个」

`xdebug.remote_host` 到底该填谁的 IP？

它不是填虚拟机自己的 IP，也不是填 127.0.0.1，而是填「运行 PHPStorm 的那台机器」的 IP —— 即宿主机在 Vagrant 网络中的可路由地址。

Xdebug 3.4.1

Xdebug 3.4.1 是一款功能强大的 PHP 调试扩展工具，于 2025 年 1 月 6 日正式发布。作为 Xdebug 3.4 系列的首个修复版本，3.4.1 版在继承上一版本强大功能的同时，重点解决了稳定性问题。该版本不仅修复了访问超全局变量时可能引发的程序崩溃现象，还增强了对 Windows 平台 PIE 构建机制的支持，为广大 PHP 开发者提供了更加稳定的调试环境。这一版本适合所有

下载

在 Vagrant 中执行：ip route | awk '/default/ {print $3}'，通常返回 10.0.2.2（VirtualBox 默认网关）或 192.168.x.x（桥接/NAT 网络下宿主机真实 IP）
Windows/macOS 宿主机上，用 ifconfig 或 ipconfig 查对应网卡的 IPv4 地址（不是 127.0.0.1，也不是 Docker 的网段）
若用 xdebug.remote_connect_back=1，Xdebug 会尝试从 HTTP 请求头（如 X-Forwarded-For）反查客户端 IP —— 但 CLI 场景下无请求头，必然失败；所以 CLI 必须显式设 xdebug.remote_host
防火墙要放行 xdebug.remote_port（默认 9000，建议改 9001 避开被占用）

PHPStorm 必须做对的三件事

光配解释器和服务器远远不够，缺一不可。

解释器必须选「Remote Interpreter」→「Vagrant」，并指向你的 Vagrantfile 所在目录；否则它根本不知道怎么连 SSH
「Run → Edit Configurations」里添加 Server，关键在「Path Mapping」：左侧填虚拟机内项目绝对路径（如 /var/www/myapp），右侧填宿主机本地项目路径（如 /Users/me/myapp）—— 错一位就找不到源码文件
点击工具栏右上角的 Start Listening for PHP Debug Connections（小虫子+手机图标），状态变绿才算开始监听；很多人点了 Debug 按钮却没点这个，连接直接被丢弃

CLI 脚本（如 drush、artisan）调试要额外加环境变量

Web 请求由 Nginx/Apache 触发，自动带 XDEBUG_CONFIG；但终端命令不会，必须手动注入。

写个包装脚本 drush-debug：

#!/bin/bash
export XDEBUG_CONFIG="idekey=PHPSTORM"
export PHP_IDE_CONFIG="serverName=myvagrant"
exec /usr/bin/drush "$@"

给它加执行权限：chmod +x drush-debug
确保 PHPStorm 中「Servers」里 serverName 和脚本里一致（大小写敏感）
如果用 php artisan，同理包装：export XDEBUG_CONFIG="idekey=PHPSTORM" && php artisan "$@"

最常被忽略的一点：Vagrant 同步文件夹类型（如 rsync）会导致断点位置错乱，优先用 nfs 或 virtiofs；若只能用 rsync，请在 PHPStorm 中关闭「Synchronize files on frame activation」，避免自动覆盖断点行号。