xdebug 3调试成功需严格配置三行：xdebug.mode=debug、xdebug.start_with_request=trigger、xdebug.client_host=127.0.0.1（或docker对应地址），缺一即静默失败；须确认扩展加载、端口9003匹配、路径映射精准、并手动触发（如?xdebug_trigger=1）。
Xdebug 3.x 不是装完就能断点，而是配对三行就通、错一行就静默失败。新手最常卡在“明明装了却没反应”，其实问题不在扩展本身，而在配置链断裂——路径没映射、触发没信号、端口不匹配，三者缺一不可。
确认Xdebug已加载
别跳过这步。打开终端执行：
- php -v：输出里必须带 Xdebug v3.x.x 字样
- php --ini：确认 php.ini 路径，然后用 php -i | grep xdebug 查是否启用
- 写个
info.php放到 Web 目录下：<?php phpinfo(); ?>，浏览器访问后搜索 “xdebug”，看到模块信息才算真正加载成功
只留这三行核心配置（Xdebug 3）
打开你的 php.ini（CLI 和 Web 环境可能不同，都要改），删掉所有旧版 remote_* 配置，末尾只加：
Xdebug 3.4.1
下载
Xdebug 3.4.1 是一款功能强大的 PHP 调试扩展工具，于 2025 年 1 月 6 日正式发布。作为 Xdebug 3.4 系列的首个修复版本，3.4.1 版在继承上一版本强大功能的同时，重点解决了稳定性问题。该版本不仅修复了访问超全局变量时可能引发的程序崩溃现象，还增强了对 Windows 平台 PIE 构建机制的支持，为广大 PHP 开发者提供了更加稳定的调试环境。这一版本适合所有
- xdebug.mode=debug：这是总开关，不设它，其他全无效
- xdebug.start_with_request=trigger：安全又省资源，只在带触发参数时连 IDE
-
xdebug.client_host=127.0.0.1：本地开发用；Docker 容器内调试宿主机请换为
host.docker.internal或网关 IP（如172.17.0.1）
端口默认 9003，不是 9000。若改了 xdebug.client_port，IDE 也必须同步调整。
让断点真正命中
VS Code 或 PhpStorm 断点变灰色？大概率是路径没对上：
- 在 PHP 脚本里加
echo __FILE__;，看实际运行路径（比如/var/www/html/index.php） - 在 IDE 的 launch.json（VS Code）或 Server Configuration（PhpStorm）中，把远程路径和本地项目路径一对一映射，注意大小写、斜杠方向、绝对路径
- 示例（VS Code）：
"pathMappings": { "/var/www/html": "${workspaceFolder}" }
手动触发调试会话
Xdebug 3 不再监听所有请求。要启动调试，必须显式发信号：
- URL 后加
?XDEBUG_TRIGGER=1（推荐，兼容性好） - 或安装 Xdebug Helper 浏览器插件（Chrome/Firefox），点击图标激活，自动注入 cookie
- 注意：
XDEBUG_SESSION_START也可用，但大小写敏感，xdebug_session_start小写无效
