xdebug.mode=debug是必须写的底线配置，因Xdebug 3废弃旧参数，所有功能由mode统一控制；不设debug则无法触发远程调试，即使其他参数全对也无效。
Xdebug 配置失败，90% 不是因为不会装，而是因为 xdebug.mode 没设对、client_host 写错了 IP、或者压根没重启 PHP-FPM —— 这些错误在日志里不报错，但断点就是不生效。
为什么 xdebug.mode=debug 是必须写的底线配置
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.client_host 在 Docker / WSL / 远程服务器上怎么填
这个值不是“本机地址”，而是 Xdebug 扩展要连接的目标机器 IP —— 即你的 IDE 所在机器的可路由地址。填错会导致连接超时，且日志里只显示 connect to 127.0.0.1:9003 failed，不提示你该填谁。
- 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 解析异常导致隐性失败
断点不命中？先查 pathMappings 和文件路径格式
PhpStorm/VS Code 收到连接后，会拿 Xdebug 发来的文件路径（如 /var/www/html/index.php）去本地找对应文件。路径对不上，断点就永远“悬空”。Windows 用户尤其容易在这里栽跟头。
立即学习“PHP免费学习笔记（深入）”；
- 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，确认路径原始值，别靠猜
页面卡死或超时？警惕 xdebug.connect_timeout_ms 和日志缺失
当 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（临时排查用）
最麻烦的从来不是参数记不住，而是改完配置忘了重启 PHP-FPM、改了 CLI 的 php.ini 却在浏览器里测试、或者以为开了 debug 就万事大吉，结果 client_host 指向了一个根本不存在的 IP —— 这些地方不验证，调三天也白搭。
