Xdebug断点调试配置详解

Xdebug断点调试失效的90%原因并非玄学或版本问题，而是配置细节出错：必须确保xdebug.mode=debug、彻底删除所有已废弃的remote_参数、客户端端口（client_port=9003）与IDE监听端口严格一致、浏览器请求携带XDEBUG_SESSION_START参数（推荐使用Xdebug Helper插件），同时注意Docker中client_host需设为host.docker.internal、PHP-FPM可能通过php_admin_value强制覆盖配置、以及路径映射在容器/远程场景下的关键作用——只要按步骤精准校准这五大核心环节，断点即可稳定触发，告别无效重启和盲目排查。

Xdebug断点不触发，90%是因为 xdebug.mode 没设成 debug，或 client_port 与 IDE 监听端口不一致——不是版本问题，更不是重启能解决的玄学。

确认 xdebug.mode=debug 且无 remote_ 参数残留

Xdebug 3.x 完全废弃 xdebug.remote_enable、xdebug.remote_host 等所有带 remote_ 前缀的配置。混用会导致 xdebug_info() 显示已加载，但断点静默失效。

• 执行 php --ri xdebug，检查输出中 xdebug.mode 的值是否包含 debug（如 debug,develop 或纯 debug）
• 打开实际生效的 php.ini（用 php --ini 确认路径），删掉所有含 remote_ 的行
• 只保留这几行核心配置（本地直连场景）：

  zend_extension=xdebug.so
  xdebug.mode=debug
  xdebug.start_with_request=trigger
  xdebug.client_host=127.0.0.1
  xdebug.client_port=9003
  xdebug.idekey=PHPSTORM

• Docker 环境下 xdebug.client_host 必须设为 host.docker.internal，不能写 localhost

IDE 必须监听 9003 端口并允许外部连接

PHP 进程主动反向连接 IDE，不是 IDE 主动连 PHP。端口不匹配或未开启监听，xdebug.log 里会出现 Connection to '127.0.0.1:9003' failed。

• PhpStorm：进入 Settings > PHP > Debug，确认 Debug port 是 9003，且勾选 Can accept external connections
• VS Code：检查 .vscode/launch.json 中 "port": 9003，启动调试会话时点绿色 ▶（不是直接按 F5）
• 命令行验证端口是否被监听：lsof -i :9003（macOS/Linux）或 netstat -ano | findstr :9003（Windows）
• Windows Defender 或其他杀毒软件可能拦截 9003 端口，需手动放行

浏览器请求必须携带 XDEBUG_SESSION_START 参数

Xdebug 不会自动监听所有请求。没有触发标识，它根本不会尝试连接 IDE，断点自然不生效。

• 最可靠方式：安装官方 Xdebug Helper 浏览器插件（Chrome/Firefox），点击虫子图标选择 Debug，它会自动在 URL 后加 ?XDEBUG_SESSION_START=PHPSTORM 并设置 Cookie
• 手动测试可用：http://localhost/test.php?XDEBUG_SESSION_START=PHPSTORM
• 确保插件里设置的 IDE Key 和 php.ini 中的 xdebug.idekey 一致（默认都是 PHPSTORM）
• xdebug.idekey 已被弃用，真正起效的是 URL 参数或 Cookie 中的 XDEBUG_SESSION_START 值

PHP-FPM 场景下注意配置覆盖问题

Web SAPI（如 Apache/mod_php）和 CLI 的 php.ini 常不同，而 PHP-FPM 更进一步：其 pool.d/www.conf 可能通过 php_admin_value[xdebug.mode] 强制覆盖全局配置，导致你改了 php.ini 却完全无效。

• 检查 /etc/php/*/fpm/pool.d/www.conf（路径依系统而异），搜索 xdebug.mode 或 php_admin_value
• 若存在类似 php_admin_value[xdebug.mode] = off，要么注释掉，要么改为 debug
• 改完后必须重启 php-fpm 服务，而非仅 reload
• CLI 调试时，php -dxdebug.start_with_request=yes script.php 不稳定，推荐用环境变量：XDEBUG_CONFIG="idekey=PHPSTORM" php script.php

路径映射（path mappings）容易被忽略：Docker、远程服务器或 WSL 下，容器内 /var/www/html 和你本地项目路径不一致时，断点会“命中但不暂停”。必须在 IDE 的 Servers 设置里启用 Use path mappings 并正确配对。

以上就是《Xdebug断点调试配置详解》的详细内容，更多关于的资料请关注golang学习网公众号！