xdebug 3.x 需精准配置四要素：扩展匹配、端口一致、路径映射正确、触发明确；仅需三行核心参数（xdebug.mode=debug、xdebug.start_with_request=trigger、xdebug.client_host=127.0.0.1），缺一不可，否则静默失败。
Xdebug 3.x 不是“装完就用”，而是配置极简但必须精准——三行核心参数配对生效，缺一即静默失败。关键不在装得多，而在配得准：扩展加载、端口一致、路径映射、触发明确，四者齐备才能断点命中。
确认当前PHP环境与扩展匹配
装错版本的 xdebug.so 是新手最常踩的坑。先执行：
- php -v：确认 PHP 主版本（如 8.2、8.3）
- php --ini：找到真实生效的 php.ini 路径
-
php -i | grep "extension_dir"：获知 .so 文件应放的位置（如
/home/user/.phpenv/versions/8.2.12/lib/php/extensions/no-debug-zts-20220829/） - php -m | grep xdebug：无输出说明未加载；有输出但版本是 v2.x，需卸载重装 v3.x
只写这三行（Xdebug 3 核心配置）
打开对应 php.ini（CLI 和 Web 环境可能不同，都要改），删掉所有 xdebug.remote_* 类旧参数，末尾仅保留：
- xdebug.mode=debug：总开关，不设它，其他全无效
- xdebug.start_with_request=trigger：按需启动，安全省资源
-
xdebug.client_host=127.0.0.1：本地开发用；Docker 容器内调试宿主机时，换成
host.docker.internal或网关 IP（如172.17.0.1）
端口默认为 9003（不是 9000），若改了 xdebug.client_port，IDE 也必须同步调整。
让 IDE 正确识别文件路径
断点变灰色？大概率是路径没对上。操作步骤：
- 在 PHP 脚本里加
echo __FILE__;，运行后看实际路径（例如/var/www/html/index.php） - VS Code 中，在
.vscode/launch.json的pathMappings里严格映射："pathMappings": { "/var/www/html": "${workspaceFolder}" } - PhpStorm 中，在 Preferences → PHP → Servers 里设置 “Absolute path on the server” 与本地项目路径一一对应
- 注意大小写、斜杠方向（Linux 用
/，Windows 项目映射时也统一用正斜杠）、必须用绝对路径
手动触发调试会话（Xdebug 3 必须显式启动）
它不再监听所有请求，必须发信号才能连 IDE：
- URL 后加
?XDEBUG_TRIGGER=1（推荐，兼容性好，大小写不敏感） - 安装浏览器插件 Xdebug Helper（Chrome/Firefox），点击图标激活，自动注入 cookie
-
XDEBUG_SESSION_START=1也可用，但注意大小写：xdebug_session_start（全小写）无效
访问带触发参数的页面后，IDE 应立即弹出调试提示 —— 此时断点才真正生效。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
