PHP调试避坑指南：Xdebug新手常犯的配置错误50例-php教程-PHP中文网

xdebug.mode=debug是必须写的底线配置，因xdebug 3废弃旧参数，所有功能由mode统一控制；不设debug则无法触发远程调试，即使其他参数全对也无效。

php调试避坑指南：xdebug新手常犯的配置错误50例

Xdebug 配置失败，90% 不是因为不会装，而是因为 xdebug.mode 没设对、client_host 写错了 IP、或者压根没重启 PHP-FPM —— 这些错误在日志里不报错，但断点就是不生效。

Xdebug 3 彻底废弃了旧版的 xdebug.remote_enable 等一堆参数，所有功能开关都收归 xdebug.mode 统一管理。不写它，哪怕其他参数全对，Xdebug 也当自己是“游客”，不触发任何调试行为。

xdebug.mode=debug 是远程调试的硬性前提；只写 develop 或 profile 都无法连接 IDE
多个模式用英文逗号分隔，比如 xdebug.mode=debug,develop，中间不能有空格
如果用了 xdebug.start_with_request=trigger，但没配 debug 模式，XDEBUG_TRIGGER 参数会被完全忽略
PHP-FPM 和 CLI 的 php.ini 可能不同，务必确认你改的是实际生效的那个配置文件（用 php --ini 和 php -i | grep "Loaded Configuration File" 双重验证）

这个值不是“本机地址”，而是 Xdebug 扩展要连接的目标机器 IP —— 即你的 IDE 所在机器的可路由地址。填错会导致连接超时，且日志里只显示 connect to 127.0.0.1:9003 failed，不提示你该填谁。

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

Docker 容器内运行 PHP：填宿主机网关，通常是 172.17.0.1（Docker 默认 bridge 网络），不是 localhost 或 host.docker.internal（后者需额外启用）
WSL2 中运行 PHP，IDE 在 Windows：填 Windows 主机 IP（如 172.28.16.1），用 cat /etc/resolv.conf | grep nameserver 查；别填 localhost，WSL2 的 localhost ≠ Windows 的 localhost
远程服务器（如 Ubuntu VM）+ 本地 VS Code：填你本机的局域网 IP（如 192.168.1.5），并确保服务器防火墙放行 9003 端口（ufw allow 9003）
开发机和 IDE 同在一地？仍建议显式写 127.0.0.1，避免因 hosts 或 DNS 解析异常导致隐性失败

PhpStorm/VS Code 收到连接后，会拿 Xdebug 发来的文件路径（如 /var/www/html/index.php）去本地找对应文件。路径对不上，断点就永远“悬空”。Windows 用户尤其容易在这里栽跟头。

Linux/macOS 服务器 + Windows IDE：服务器路径是正斜杠 /var/www/html/，本地路径却是 E:/project/ —— 必须在 IDE 的调试配置中做映射，例如 VS Code 的 launch.json 里写："pathMappings": { "/var/www/html/": "${workspaceFolder}/" }
WAMP/XAMPP 用户常见坑：DocumentRoot 是 E:\wamp64\www\myapp，但 Xdebug 发送的路径可能是 E:/wamp64/www/myapp/index.php（混用斜杠），IDE 识别为不同路径；解决方案是统一用正斜杠，并在 PhpStorm 的 Deployment > Path mappings 中把服务器路径设为 /，本地路径设为项目根目录
ThinkPHP/Laravel 等框架常把入口放在 public/ 子目录，但 Xdebug 报告的路径是 /var/www/html/public/index.php —— 映射时一定要包含 public/，否则断点打在 app/ 里根本不会触发
用 xdebug_info() 函数输出当前请求的 script_filename 和 remote_addr，确认路径原始值，别靠猜

当 IDE 没监听、或网络不通时，Xdebug 默认会阻塞脚本执行，直到连接超时（默认 200ms）。若你误设 xdebug.connect_timeout_ms=0，请求就会无限等待，Nginx 返回 504，而 PHP 错误日志里一片空白。

生产环境必须禁用 Xdebug：确保 xdebug.mode 不含 debug，且 zend_extension 行被注释或移除
开发中想按需触发？用 xdebug.start_with_request=trigger + 浏览器插件（Xdebug Helper）或手动加 ?XDEBUG_TRIGGER=1，比每次都连更安全
诊断阻塞问题，第一件事是开日志：xdebug.log_level=10 + xdebug.log=/tmp/xdebug.log，然后 tail -f /tmp/xdebug.log 看是否反复出现 Connecting to configured address/port 和 Failed to connect
日志目录权限必须放开：sudo chown -R www-data:www-data /tmp/xdebug（PHP-FPM 用户）或 chmod 777 /tmp/xdebug（临时排查用）