xdebug.mode=debug是xdebug 3启用调试的必需开关，仅加载zend_extension或使用旧版remote_enable无效；必须显式设置且与client_host、client_port、ide监听端口一致，并通过url参数、插件或环境变量触发会话。
确认 xdebug.mode 配置是否启用 debug 模式
xdebug 3 默认不开启远程调试，xdebug.mode 必须显式包含 debug，仅靠 zend_extension 加载或旧版的 xdebug.remote_enable=1 完全无效。PHP 启动时若没看到 XDEBUG_CONFIG 环境变量或 IDE 接收不到连接请求，大概率卡在这一步。
-
xdebug.mode = debug是最低要求；如需同时用 profiling 或 trace，可设为debug,profile - 不要混用 xdebug 2 风格配置（如
xdebug.remote_host），它们在 xdebug 3 中被完全废弃 - 通过
php -i | grep xdebug.mode验证实际生效值，注意 CLI 和 FPM 的 php.ini 可能不同
检查 xdebug.client_host 和 client_port 是否匹配 IDE 监听地址
xdebug 3 改用主动反向连接（xdebug → IDE），不再由 IDE 主动连 PHP 进程。所以 xdebug.client_host 必须填 IDE 所在机器能被 PHP 进程路由到的 IP，常见错误是填了 localhost 或 127.0.0.1 却运行在 Docker 容器或远程服务器中。
- Docker 内 PHP：用
xdebug.client_host = host.docker.internal（Mac/Win）或宿主机真实 IP（Linux） - WSL2 中 PHP：填 Windows 主机的 WSL2 可达 IP（如
172.x.x.1），不是localhost - IDE 默认监听
9003端口（xdebug 3 新默认），确保xdebug.client_port = 9003且 IDE 设置一致 - 防火墙或 SELinux 可能拦截出站连接，用
telnet $CLIENT_HOST 9003在 PHP 所在环境验证连通性
验证触发条件：IDE key、cookie 与触发方式是否对齐
断点不触发，常因 xdebug 根本没启动调试会话。xdebug 3 不再默认监听所有请求，必须显式触发：
- 浏览器插件（Xdebug Helper）需将 IDE key 设为与 IDE 中配置完全一致的字符串，例如
PHPSTORM - 手动加 URL 参数
?XDEBUG_SESSION_START=PHPSTORM最直接，避免插件缓存或失效干扰 - CLI 调试需额外设置环境变量：
XDEBUG_CONFIG="idekey=PHPSTORM" php script.php - 检查响应头是否含
X-Xdebug-Session，有则说明 xdebug 已介入；无则说明未触发或配置被覆盖（如 .htaccess 或 php-fpm pool 中重置了 ini 值）
留意 PHP-FPM 与 Apache/Nginx 的进程模型差异
FPM worker 进程复用会导致 xdebug 配置“看似生效但不持续”，尤其在 reload/restart 后首次请求正常、后续失效。根本原因是 xdebug 会话状态绑定在单个 worker 上，而某些配置（如 xdebug.start_with_request）在 FPM 下行为不稳定。
- 开发期建议设
xdebug.start_with_request = trigger（推荐）或yes，避免依赖 worker 生命周期 - Apache + mod_php 通常更稳定，但若用了
mpm_event模块，仍可能因多线程导致调试连接丢失 - 务必禁用 opcache 在开发环境（
opcache.enable=0），否则修改代码后断点位置可能错位 - 查看
/var/log/php-fpm.log或error_log，搜索Xdebug: [Step Debug]开头日志，确认连接尝试是否发出
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
