Xdebug调试失败主因是xdebug.mode配置错误、client_host指向错误或PHP-FPM进程模型导致连接丢弃；必须显式设mode=debug，client_host按环境配宿主机IP或host.docker.internal，禁用ondemand模式改用static以保连接稳定。
直接上结论：Nginx + PHP-FPM 环境下，Xdebug 调试失败，90% 是因为 xdebug.mode 配置错误、xdebug.client_host 指向不对，或 PHP-FPM 的进程模型导致调试连接被丢弃。
确认 Xdebug 版本与 mode 模式是否匹配
Xdebug 3 彻底重构了启用机制，不再用 xdebug.remote_enable 这类旧参数。如果你沿用网上搜到的 Xdebug 2 配置，必然不生效。
-
xdebug.mode必须显式设置，常见组合：debug（单步调试）、debug,develop（加开发辅助）、off（禁用） - 仅设
xdebug.start_with_request=yes不够——它依赖mode=debug已启用，否则直接忽略 - 检查输出：
php -v应显示with Xdebug v3.x.x；php --ri xdebug查看实际生效的mode值
正确配置 client_host 和 client_port
Nginx 本身不参与 Xdebug 连接，关键在 PHP-FPM 子进程能否反向连回你的 IDE（如 PhpStorm、VS Code）。本地开发最常踩的坑是 xdebug.client_host 写成 127.0.0.1 却没意识到 PHP-FPM 容器/子进程网络上下文不同。
- Linux/macOS 本地直连：用
xdebug.client_host=127.0.0.1，IDE 监听9003（Xdebug 3 默认端口） - Docker 环境（PHP-FPM 在容器内）：不能写
127.0.0.1，而应写宿主机网关，例如xdebug.client_host=host.docker.internal（Docker Desktop）或宿主机真实 IP - 避免端口冲突：
xdebug.client_port=9003，确保 IDE 没被其他服务（如老版本 Xdebug、Web Server）占掉该端口
PHP-FPM 的运行模式影响调试稳定性
PHP-FPM 默认用 ondemand 或 dynamic 模式启停子进程。Xdebug 连接是短时 TCP 反向连接，若子进程在响应结束后立即退出，IDE 可能收不到断点响应。
立即学习“PHP免费学习笔记（深入）”；
- 开发阶段建议临时改为
static模式，保持固定数量子进程常驻：pm = static，pm.max_children = 5 - 确认
php-fpm.conf或 pool 配置中未覆盖clear_env = no——否则 Xdebug 环境变量（如XDEBUG_CONFIG）会被清空 - 浏览器触发调试需带
XDEBUG_SESSION_START=PHPSTORM参数（或用浏览器插件），但更可靠的是在请求头加Cookie: XDEBUG_SESSION=PHPSTORM
最容易被忽略的一点：Nginx 的 fastcgi_param 不转发 Xdebug 相关环境变量，所以不要试图在 location ~ \.php$ 块里加 fastcgi_param PHP_VALUE "xdebug.mode=debug" ——PHP-FPM 不认这个，必须在 php.ini 或 conf.d/xdebug.ini 里硬编码配置。
