必须用xdebug.mode=debug，Xdebug 3已废弃xdebug.remote_enable=1；若断点无反应，八成是该参数未设对或php.ini路径错误，且需确保zend_extension路径准确、端口与IDE一致、pathMappings映射正确。
php.ini 必须用 xdebug.mode=debug，不是 remote_enable
断点点了没反应？八成是 xdebug.mode 没设对。Xdebug 3 彻底废弃了 xdebug.remote_enable=1 这类旧参数，写了也白写，还会干扰加载。必须显式启用调试模式：
-
xdebug.mode=debug是唯一触发断点的开关（可加develop或profile，但debug缺不得） - 如果
phpinfo()页面里搜不到xdebug.mode这一行，说明 Xdebug 根本没加载，或版本低于 3.0 - CLI 和 Web SAPI 加载的
php.ini常不是同一份：PHPStorm 的 CLI 解释器配置页里看Configuration file路径；浏览器访问phpinfo()看Loaded Configuration File—— 两者必须一致，否则断点只在终端或只在浏览器生效
zend_extension 路径必须绝对准确，且不能和 Zend 工具共存
zend_extension 指向的 DLL 或 SO 文件路径错一个字符，Xdebug 就静默失败。更隐蔽的是：Zend Debugger、Zend Optimizer 这类扩展会直接拦截 Xdebug 启动。
- Windows 下路径示例：
zend_extension=C:\phpenv\versions\8.2.12\ext\php_xdebug-3.3.1-8.2-vs17-x86_64.dll（注意.dll后缀和完整文件名） - Linux/macOS 下路径示例：
zend_extension=/usr/lib/php/20220829/xdebug.so（用php -i | grep extension_dir确认目录） - 删掉或注释掉所有
zend_extension=<path_to_zend_debugger>和zend_extension=<path_to_zend_optimizer>行 - 改完后重启 Web 服务（Apache/Nginx）和 PHP-FPM（如用），仅重启 PHPStorm 不起作用
端口、client_host、IDE key 三者必须同步对齐
PHPStorm 点「Start Listening」没反应？不是按钮坏了，是连接被拦在半路。Xdebug 3 默认主动连回 IDE，不是 IDE 被动等连接。
-
xdebug.client_port=9003（Xdebug 3 默认值），必须和 PHPStorm 设置中Settings > Languages & Frameworks > PHP > Debug > Xdebug > Debug port完全一致 -
xdebug.client_host=127.0.0.1仅适用于本地开发；Docker 容器内 PHP 需改成host.docker.internal（macOS/Windows）或宿主机真实 IP（Linux） -
xdebug.idekey=PHPSTORM必须和 PHPStorm 的Settings > PHP > Debug > DBGp Proxy > IDE key完全一致（区分大小写）；不填也可，但填了就必须对上 - 防火墙可能拦截 9003 端口入站连接，临时关闭测试：
sudo ufw disable（Ubuntu）或检查 Windows 入站规则
路径映射（Path Mapping）填反了，断点就跳到空白文件
断点命中但变量全空、堆栈显示 ???、跳转到错误文件？大概率是服务器路径没“翻译”成你本地路径。
立即学习“PHP免费学习笔记（深入）”；
- Xdebug 发送的是服务器上的绝对路径，比如
/var/www/html/index.php；PHPStorm 必须把它映射到你本地打开的路径，比如/Users/me/project/index.php - 在 PHPStorm 的
Settings > Languages & Frameworks > PHP > Servers里添加对应域名（如localhost），然后点击右侧...配置Path mappings - 左侧填服务器路径（
/var/www/html），右侧填本地路径（/Users/me/project）——方向反了就找不到文件 - 若用 phpEnv 或 WAMP，路径通常是
C:\phpstudy\WWW映射到你本地项目目录
xdebug.log=C:\temp\xdebug.log（Windows）或 xdebug.log=/tmp/xdebug.log（Linux/macOS），确保目录可写，再复现问题看日志里卡在哪一步。 
